feat(security): implement FW-N5, FW-N6, FW-N7 (HMAC-SHA256 protocol docs, auto-generate token, replay attack defense)
This commit is contained in:
@@ -41,6 +41,9 @@
|
||||
| FW-N3 | 로그 문구 "auth_token mismatch" -> "HMAC verify failed" 갱신 | `5258b50` | Hermes 직접 | job_subscriber.py drop 로그 문구 수정 완료 (PASS) |
|
||||
| FW-N4 | MESSAGING.md §2.4 HMAC 기술 갱신 및 롤아웃 정의 | `5258b50` | Hermes 직접 | 보고서 §2.4 최신화 완료 (PASS) |
|
||||
| Infra | 분석 인프라 개선 (Pane snapshotting / truncate 방지 가이드라인 반영) | `5258b50` | Hermes 직접 | delegate-job SKILL.md에 pane 캡처 3대 규칙 반영 (PASS) |
|
||||
| FW-N5 | `job-protocol.md` 보안 프로토콜 규격 갱신 (HMAC 서명 기준) | `cc77cdd` | Hermes 직접 | 문서/설계 정합성 패스 완료 (PASS) |
|
||||
| FW-N6 | `registry.py` 내 `auth_token` 자동 생성 및 CLI 연동 지원 | `cc77cdd` | Hermes 직접 | `--auth-token` 인자 추가 및 보안 브로커 감지 시 자동 생성 처리 완료 (PASS) |
|
||||
| FW-N7 | `job_subscriber.py` 내 시퀀스 단조 증가 검증을 통한 Replay Attack 방어 | `cc77cdd` | Hermes 직접 | Watcher 내 last_seq 추적 및 seq 단조 증가 검사 로직 구현 완료 (PASS) |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -41,6 +41,9 @@
|
||||
| FW-N3 | Update log string "auth_token mismatch" -> "HMAC verify failed" | `5258b50` | Hermes Direct | Updated drop log text in `job_subscriber.py` (PASS) |
|
||||
| FW-N4 | Update HMAC technical description and rollout definition in `MESSAGING.md` §2.4 | `5258b50` | Hermes Direct | Updated report §2.4 (PASS) |
|
||||
| Infra | Improve analysis infrastructure (implemented pane snapshotting to prevent truncation) | `5258b50` | Hermes Direct | Documented the 3 pane capture rules in delegate-job `SKILL.md` (PASS) |
|
||||
| FW-N5 | Update `job-protocol.md` security protocol spec (to HMAC signatures) | `cc77cdd` | Hermes Direct | Documentation/Design consistency pass completed (PASS) |
|
||||
| FW-N6 | Support auto-generated `auth_token` and CLI integration in `registry.py` | `cc77cdd` | Hermes Direct | Added `--auth-token` argument, auto-generation on secure broker detection (PASS) |
|
||||
| FW-N7 | Prevent Replay Attacks via sequence monotonic increase validation in `job_subscriber.py` | `cc77cdd` | Hermes Direct | Added seq tracking in watcher to verify monotonic increase (PASS) |
|
||||
|
||||
---
|
||||
|
||||
|
||||
+1
-10
@@ -12,20 +12,11 @@
|
||||
|
||||
| ID | 과제명 | 우선순위 | 작업량 | 해결 분야 / 설명 | 의존성 |
|
||||
|---|---|---|---|---|---|
|
||||
| **FW-N5** | `job-protocol.md` 보안 프로토콜 규격 갱신 (HMAC 서명 기준) | P1 (High) | 소 (문서) | **문서/설계 정합성**: 정식 프로토콜 문서가 보안상 불안전한 평문 토큰 전송 스킴(`data.auth_token`)으로 잘못 안내되어 있는 문제를 실제 구현된 HMAC 서명 스킴에 맞게 수정 | 없음 (FW-N6와 병행) |
|
||||
| **FW-N6** | `registry.py` 내 `auth_token` 자동 생성 및 CLI 연동 지원 | P1 (High) | 소~중 | **보안 기능 활성화**: 현재 CLI(`registry.py register`)로 등록되는 모든 잡의 `auth_token`이 항상 `null`(무인증)로 고정되어 HMAC 보안이 무력화되는 결함 해결. CLI에 `--auth-token` 인자를 추가하고, 보안 환경(TLS/Username 등) 감지 시 자동으로 토큰을 생성하도록 개선 | 없음 (최우선 과제) |
|
||||
| **FW-N7** | `job_subscriber.py` 내 시퀀스 단조 증가 검증을 통한 Replay Attack 방어 | P2 (Medium) | 소~중 | **보안성 강화 (심층 방어)**: 암호화 서명된 비단말(non-terminal) 이벤트(`progress`, `permission_required`)가 네트워크 상에서 탈취되어 재전송(Replay)되는 것을 방지하기 위해, 수신 메시지의 시퀀스(`seq`) 단조 증가 확인 로직 추가 | **FW-N6 선행 필수** (인증/HMAC 활성화 이후 의미 있음) |
|
||||
| **FW-L4** | Job Registry의 SQLite 마이그레이션 및 NFS flock 한계 극복 | P3 (Low) | 대 | **동시성/인프라 확장성**: 세션 레지스트리와 마찬가지로 개별 JSON 파일 락(`fcntl.flock`) 방식의 잡 레지스트리를 SQLite 데이터베이스 트랜잭션 구조로 통합 마이그레이션하여, NFS 등 분산/네트워크 FS 환경에서의 안정성을 완전 확보 | **조건부** (실제 멀티 호스트/NFS 배포 필요 발생 시 착수) |
|
||||
|
||||
---
|
||||
|
||||
### 세부 논의 결과 및 방향성 (Reviewer 합의 사항)
|
||||
|
||||
1. **HMAC 보안 활성화를 위한 R2(FW-N6) 우선 해결**:
|
||||
* 현재 구현된 HMAC 서명 코드(Verify/Sign)는 실재하지만, 정상적인 CLI 경로로 잡을 등록할 때는 암호화 토큰을 생성 또는 주입할 방법이 전무해 강제로 무인증 PoC 모드로 실행됩니다. 따라서 **FW-N6**가 모든 보안 개선의 선행 고리입니다.
|
||||
2. **문서 동기화(FW-N5)**:
|
||||
* 문서가 안전하지 않은 설계(평문 전송)를 가이드하고 있으므로 개발 혼선을 막기 위해 즉각 수정합니다.
|
||||
3. **Replay 공격 방어(FW-N7)의 범위**:
|
||||
* 시퀀스 단조 증가 검사(`last_seq` 추적)를 수신단에 구현하되, 가입자(`job_subscriber.py`) 재시작 시의 `last_seq` 초기화 예외 처리 및 터미널 이벤트 중복 제어와의 연계를 정밀히 검토해야 합니다.
|
||||
4. **SQLite 통합(FW-L4)의 조건부 연기**:
|
||||
1. **SQLite 통합(FW-L4)의 조건부 연기**:
|
||||
* 세션 레지스트리와 달리 개별 잡 데이터는 JSON 파일 구조가 관리 및 디버깅 직관성이 우수하며, 현재 배포 환경은 단일 호스트 로컬 FS로 제한되어 있어 `fcntl.flock` 잠금만으로 안전하게 운용 가능하므로 낮은 우선순위(P3)로 배정하고 필요 시 착수합니다.
|
||||
+1
-10
@@ -12,20 +12,11 @@ Below is the list of pending future work items. These items were proposed based
|
||||
|
||||
| ID | Task | Priority | Effort | Domain / Description | Dependencies |
|
||||
|---|---|---|---|---|---|
|
||||
| **FW-N5** | Update `job-protocol.md` security protocol spec (to HMAC signatures) | P1 (High) | Small (Doc) | **Documentation/Design Consistency**: Fix the official protocol document which incorrectly guides users to use an insecure plaintext token transmission scheme (`data.auth_token`), aligning it with the actually implemented HMAC signature scheme. | None (conduct in parallel with FW-N6) |
|
||||
| **FW-N6** | Support auto-generated `auth_token` and CLI integration in `registry.py` | P1 (High) | Small~Medium | **Activate Security Features**: Resolve the bug where all jobs registered via CLI (`registry.py register`) have `auth_token` set to `null` (unauthenticated mode), which bypasses HMAC security. Add the `--auth-token` argument to the CLI, and automatically generate a token when a secure environment (TLS/Username, etc.) is detected. | None (Highest Priority) |
|
||||
| **FW-N7** | Prevent Replay Attacks via sequence monotonic increase validation in `job_subscriber.py` | P2 (Medium) | Small~Medium | **Security Hardening (Defense in Depth)**: To prevent cryptographically signed non-terminal events (`progress`, `permission_required`) from being intercepted on the network and retransmitted (Replay Attack), add logic to verify that the sequence number (`seq`) of incoming messages is monotonically increasing. | **FW-N6 is a prerequisite** (only meaningful after authentication/HMAC is active) |
|
||||
| **FW-L4** | Migrate Job Registry to SQLite to overcome NFS flock limitations | P3 (Low) | Large | **Concurrency/Infrastructure Scalability**: Similar to the Session Registry, migrate the individual JSON file lock (`fcntl.flock`) registry structure into an integrated SQLite database transaction structure, guaranteeing full reliability in distributed/network file systems like NFS. | **Conditional** (commence only when multi-host/NFS deployment is required) |
|
||||
|
||||
---
|
||||
|
||||
### Detailed Discussion Results & Directions (Reviewer Consensus)
|
||||
|
||||
1. **Prioritize R2 (FW-N6) to Enable HMAC Security**:
|
||||
* Although the HMAC signature code (verify/sign) is implemented, registering a job via the normal CLI lacks a way to generate or inject a cryptographic token, forcing jobs into unauthenticated PoC mode. Thus, **FW-N6** is the prerequisite for all security improvements.
|
||||
2. **Document Synchronization (FW-N5)**:
|
||||
* Since the current document details an insecure design (plaintext token transmission), it should be updated immediately to prevent development confusion.
|
||||
3. **Scope of Replay Attack Prevention (FW-N7)**:
|
||||
* Implement sequence monotonic check (`last_seq` tracking) on the receiving side. Pay careful attention to handling subscriber restarts (initializing `last_seq`) and coordinate this with terminal event duplicate controls.
|
||||
4. **Conditional Deferral of SQLite Integration (FW-L4)**:
|
||||
1. **Conditional Deferral of SQLite Integration (FW-L4)**:
|
||||
* Unlike the session registry, maintaining individual job data in JSON files is highly intuitive for management and debugging. Since the current deployment is constrained to a single-host local file system, `fcntl.flock` locks are sufficient. Thus, this is assigned a low priority (P3) and will be tackled conditionally.
|
||||
@@ -83,14 +83,10 @@ The payload shape is unchanged; the transport and trust model tighten. See
|
||||
|
||||
- **Auth / ACL** — username/password + per-topic ACL. `jobs/+/events` publish is
|
||||
granted to the worker credential, subscribe to the Hermes credential.
|
||||
- **`auth_token` (the bonus field)** — each job record carries a per-job
|
||||
`auth_token` (`secrets.token_urlsafe(32)`). The publisher copies it into
|
||||
**`data.auth_token`**; the subscriber compares it against the registry's
|
||||
expected token and **drops mismatches**. This is an integrity check on top of
|
||||
the broker ACL, useful while still on a shared/public broker.
|
||||
- **HMAC Signature Verification (`data.hmac_sig`)** — to authenticate the publisher and verify message integrity without exposing the raw secret token over the wire, each job record contains a per-job `auth_token` (`secrets.token_urlsafe(32)`). The publisher computes an HMAC-SHA256 signature over the serialized payload (excluding `data.hmac_sig` itself) using the `auth_token` as the key, and appends it to **`data.hmac_sig`**. The subscriber reconstructs this signature and **drops any message that does not match or lacks a valid signature**.
|
||||
|
||||
```json
|
||||
{ "...": "...", "data": { "auth_token": "9f3c…", "build_id": "42" } }
|
||||
{ "...": "...", "data": { "hmac_sig": "d2f3...", "build_id": "42" } }
|
||||
```
|
||||
|
||||
- **TLS** — port 8883 + private CA. Toggled with `MQTT_TLS=1` (+ `MQTT_CA_CERTS`);
|
||||
|
||||
@@ -63,6 +63,7 @@ class _Watcher:
|
||||
self.events: "queue.Queue[Tuple[str, Dict[str, Any]]]" = queue.Queue()
|
||||
self.expected = set(expected_job_ids)
|
||||
self.tokens = expected_tokens # job_id -> expected auth_token (or None)
|
||||
self.last_seq: Dict[str, int] = {jid: 0 for jid in expected_job_ids}
|
||||
|
||||
def on_message(self, _client, _userdata, msg) -> None:
|
||||
# --- defensive parsing -------------------------------------------
|
||||
@@ -87,6 +88,16 @@ class _Watcher:
|
||||
if not mqtt_common.verify_hmac(payload, expected_token):
|
||||
logger.warning("drop event for job %s: HMAC verify failed", jid)
|
||||
return
|
||||
# --- replay attack defense: check monotonic sequence ---
|
||||
seq = payload.get("seq")
|
||||
if seq is None or not isinstance(seq, int):
|
||||
logger.warning("drop event for job %s: missing or invalid seq", jid)
|
||||
return
|
||||
if seq <= self.last_seq.get(jid, 0):
|
||||
logger.warning("drop event for job %s: seq %d is not monotonically increasing (last %d)",
|
||||
jid, seq, self.last_seq.get(jid, 0))
|
||||
return
|
||||
self.last_seq[jid] = seq
|
||||
# Persistent audit log from the *subscriber's* vantage point: every event
|
||||
# that survives defensive parsing is recorded here, including ones a
|
||||
# different host published. This is the external-observer record that
|
||||
|
||||
@@ -68,6 +68,11 @@ def register_job(
|
||||
job_id = job_id or generate_job_id(bits)
|
||||
if broker is None:
|
||||
broker = broker_config_from_env().to_registry_block()
|
||||
if auth_token is None:
|
||||
# Auto-generate token if secure broker configuration (TLS or username) is detected
|
||||
if broker.get("tls") or broker.get("username"):
|
||||
import secrets
|
||||
auth_token = secrets.token_urlsafe(32)
|
||||
now = _utcnow()
|
||||
record: Dict[str, Any] = {
|
||||
"schema_version": SCHEMA_VERSION,
|
||||
@@ -191,6 +196,7 @@ def _build_parser() -> argparse.ArgumentParser:
|
||||
p_reg.add_argument("--idle-timeout", type=int, default=120)
|
||||
p_reg.add_argument("--bits", type=int, default=32, help="32 (PoC) or 128 (prod)")
|
||||
p_reg.add_argument("--artifact", action="append", default=[], dest="artifacts")
|
||||
p_reg.add_argument("--auth-token", default=None, help="HMAC auth token for the job (auto-generated if secure broker is detected)")
|
||||
|
||||
p_list = sub.add_parser("list", help="list jobs (optionally by status)")
|
||||
p_list.add_argument("--status", default=None)
|
||||
@@ -240,6 +246,7 @@ def main(argv: Optional[List[str]] = None) -> int:
|
||||
registry_dir=rd,
|
||||
expected_artifacts=args.artifacts,
|
||||
bits=args.bits,
|
||||
auth_token=args.auth_token,
|
||||
)
|
||||
print(job_id)
|
||||
return 0
|
||||
|
||||
Reference in New Issue
Block a user