-
Notifications
You must be signed in to change notification settings - Fork 102
feat(traffic-guardian): add runtime monitoring skill baselines #217
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,8 @@ | ||
| # Changelog | ||
|
|
||
| ## [0.0.1-beta1] - 2026-05-10 | ||
|
|
||
| - Added baseline skill metadata, frontmatter, and implementation specification. | ||
| - Reserved folder structure for Hermes traffic-monitoring runtime code, posture export, and tests. | ||
| - Beta release notes: this release is a scaffold/spec baseline and does not yet ship active runtime proxy interception. | ||
| - Beta release notes: defaults remain non-invasive (no automatic traffic mutation or enforcement enabled by default). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,18 @@ | ||
| # Hermes Traffic Guardian | ||
|
|
||
| Baseline skill for Hermes runtime traffic monitoring. | ||
|
|
||
| This package is intentionally a spec scaffold. Builders should add the Hermes-specific monitor implementation here while preserving the safety contract in `SKILL.md` and `SPEC.md`. | ||
|
|
||
| ## Intended Capability | ||
|
|
||
| - detect outbound secret exfiltration in Hermes HTTP/HTTPS traffic | ||
| - detect inbound command-injection and tool-abuse payloads | ||
| - write redacted local JSONL findings | ||
| - export monitor posture for `hermes-attestation-guardian` | ||
| - provide explicit start, stop, status, and log-query commands | ||
|
|
||
| ## Builder Notes | ||
|
|
||
| Keep runtime ownership in this skill. `hermes-attestation-guardian` should only attest this skill's state, config, and output fingerprints. | ||
|
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,68 @@ | ||
| --- | ||
| name: hermes-traffic-guardian | ||
| version: 0.0.1-beta1 | ||
| description: Hermes runtime traffic monitoring baseline for opt-in proxy inspection, egress detection, and attestation-aware traffic posture. | ||
| homepage: https://clawsec.prompt.security | ||
| author: prompt-security | ||
| license: AGPL-3.0-or-later | ||
| hermes: | ||
| emoji: "TG" | ||
| requires: | ||
| bins: [node, python3] | ||
| --- | ||
|
|
||
| # Hermes Traffic Guardian | ||
|
|
||
| This is a baseline specification skill. It intentionally does not ship a proxy or runtime implementation yet. | ||
|
|
||
| ## Scope | ||
|
|
||
| Builders should use this skill as the Hermes landing zone for runtime traffic monitoring: | ||
|
|
||
| - operator-scoped HTTP proxy inspection | ||
| - optional HTTPS inspection with per-process CA trust | ||
| - outbound exfiltration detection | ||
| - inbound injection detection | ||
| - redacted local threat logs | ||
| - status export for `hermes-attestation-guardian` | ||
|
|
||
| Do not add proxy runtime ownership to `hermes-attestation-guardian`. That skill should attest this monitor's status and configuration, not run it. | ||
|
|
||
| ## Safety Contract | ||
|
|
||
| - Opt-in only. | ||
| - Detect-and-log by default. | ||
| - No automatic system CA installation. | ||
| - No global proxy environment changes. | ||
| - No blocking in the first implementation. | ||
| - Redact secrets before logs, summaries, or attestation-linked outputs. | ||
| - Keep all state under `HERMES_TRAFFIC_GUARDIAN_HOME` or `$HERMES_HOME/security/traffic-guardian`. | ||
|
|
||
| ## Builder Entry Points | ||
|
|
||
| Read `SPEC.md` before implementing. Use the placeholder folders as follows: | ||
|
|
||
| | Path | Intended use | | ||
| |---|---| | ||
| | `lib/` | Detector rules, redaction, posture export, report formatting | | ||
| | `scripts/` | Start, stop, status, config validation, log query, attestation export helpers | | ||
| | `test/` | Unit tests, proxy fixture tests, redaction tests, attestation export tests | | ||
|
|
||
| ## Required First Implementation Behavior | ||
|
|
||
| 1. Validate config without starting the proxy. | ||
| 2. Start monitor in foreground or explicit background mode. | ||
| 3. Scope proxy environment variables to the target Hermes service or CLI process. | ||
| 4. Inspect HTTP request/response text up to a bounded byte limit. | ||
| 5. Support optional HTTPS MITM only when the operator supplies per-process trust configuration. | ||
| 6. Emit JSONL findings with redacted snippets. | ||
| 7. Export a small posture JSON file that `hermes-attestation-guardian` can include as a trust anchor or watched file. | ||
|
|
||
| ## Out of Scope for v0.0.1 Implementation | ||
|
|
||
| - automatic system trust-store mutation | ||
| - transparent network interception | ||
| - default blocking | ||
| - sending traffic to external services | ||
| - collecting full request/response bodies | ||
|
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,103 @@ | ||
| # Hermes Traffic Guardian Specification | ||
|
|
||
| ## Goal | ||
|
|
||
| Provide Hermes with opt-in runtime traffic monitoring that observes Hermes HTTP/HTTPS traffic for exfiltration and injection signals and exports monitor posture for attestation. | ||
|
|
||
| ## Required Architecture | ||
|
|
||
| Implement three layers: | ||
|
|
||
| 1. Detector core | ||
| - normalized finding schema | ||
| - pattern registry | ||
| - snippet redaction | ||
| - deduplication | ||
| - JSONL report writer | ||
|
|
||
| 2. Hermes adapter | ||
| - lifecycle commands for start, stop, status, and threats | ||
| - process-scoped proxy environment guidance | ||
| - posture export compatible with `hermes-attestation-guardian` | ||
|
|
||
| 3. Operator interface | ||
| - safe setup text | ||
| - explicit per-process proxy export commands | ||
| - CA fingerprint display when HTTPS inspection is enabled | ||
|
|
||
| ## Finding Schema | ||
|
|
||
| Findings must be JSON objects with these fields: | ||
|
|
||
| ```json | ||
| { | ||
| "schema_version": "clawsec-traffic-finding/v1", | ||
| "platform": "hermes", | ||
| "direction": "outbound", | ||
| "protocol": "http", | ||
| "threat_type": "EXFIL", | ||
| "pattern": "ai_api_key", | ||
| "severity": "high", | ||
| "source": "127.0.0.1", | ||
| "dest": "api.example.com:443", | ||
| "snippet": "[REDACTED]", | ||
| "timestamp": "2026-04-26T00:00:00.000Z" | ||
| } | ||
| ``` | ||
|
|
||
| ## Posture Export Schema | ||
|
|
||
| The first implementation must write a small posture file for attestation: | ||
|
|
||
| ```json | ||
| { | ||
| "schema_version": "clawsec-traffic-posture/v1", | ||
| "platform": "hermes", | ||
| "monitor_status": "running", | ||
| "mode": "detect", | ||
| "https_inspection": false, | ||
| "ca_fingerprint_sha256": null, | ||
| "config_sha256": "hex", | ||
| "finding_log_sha256": "hex", | ||
| "generated_at": "2026-04-26T00:00:00.000Z" | ||
| } | ||
| ``` | ||
|
|
||
| ## Minimum Detection Set | ||
|
|
||
| Outbound EXFIL: | ||
|
|
||
| - AI API keys | ||
| - AWS access key IDs | ||
| - private key PEM markers | ||
| - SSH key file paths | ||
| - sensitive Unix file paths | ||
| - dotenv and cloud credential paths | ||
|
|
||
| Inbound INJECTION: | ||
|
|
||
| - pipe-to-shell commands | ||
| - shell exec flags | ||
| - reverse shell command shapes | ||
| - destructive remove commands | ||
| - SSH authorized-key injection shapes | ||
|
|
||
| ## Safety Requirements | ||
|
|
||
| - Default mode is detect-and-log. | ||
| - Blocking mode must not exist in the first implementation. | ||
| - Snippets must be redacted before persistence. | ||
| - Maximum scan bytes must be configurable and bounded. | ||
| - CA trust must be per-process by default. | ||
| - System trust-store instructions must require explicit operator confirmation and must never run automatically. | ||
|
|
||
| ## Tests Required Before Release | ||
|
|
||
| - detector unit tests for each pattern | ||
| - redaction tests proving secrets are not persisted | ||
| - proxy fixture tests for HTTP request and response inspection | ||
| - no-false-positive tests for common benign traffic | ||
| - lifecycle tests for stale PID/state cleanup | ||
| - posture export schema and digest tests | ||
| - compatibility tests showing `hermes-attestation-guardian` can watch or hash the posture export | ||
|
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
|
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
|
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,112 @@ | ||
| { | ||
| "name": "hermes-traffic-guardian", | ||
| "version": "0.0.1-beta1", | ||
| "description": "Hermes runtime traffic monitoring baseline for opt-in proxy inspection, egress detection, and attestation-aware traffic posture.", | ||
| "author": "prompt-security", | ||
| "license": "AGPL-3.0-or-later", | ||
| "homepage": "https://clawsec.prompt.security/", | ||
| "platform": "hermes", | ||
| "keywords": [ | ||
| "security", | ||
| "hermes", | ||
| "traffic-monitoring", | ||
| "egress", | ||
| "exfiltration", | ||
| "injection", | ||
| "proxy", | ||
| "mitm", | ||
| "attestation", | ||
| "runtime" | ||
| ], | ||
| "sbom": { | ||
| "files": [ | ||
| { | ||
| "path": "SKILL.md", | ||
| "required": true, | ||
| "description": "Hermes traffic guardian skill instructions and operating model" | ||
| }, | ||
| { | ||
| "path": "README.md", | ||
| "required": true, | ||
| "description": "Human-oriented overview and builder handoff notes" | ||
| }, | ||
| { | ||
| "path": "CHANGELOG.md", | ||
| "required": true, | ||
| "description": "Version history and baseline release notes" | ||
| }, | ||
| { | ||
| "path": "SPEC.md", | ||
| "required": true, | ||
| "description": "Implementation specification for Hermes runtime traffic monitoring" | ||
| }, | ||
| { | ||
| "path": "lib/.gitkeep", | ||
| "required": false, | ||
| "description": "Placeholder for shared detector, posture, and report code" | ||
| }, | ||
| { | ||
| "path": "scripts/.gitkeep", | ||
| "required": false, | ||
| "description": "Placeholder for lifecycle, status, and attestation export scripts" | ||
| }, | ||
| { | ||
| "path": "test/.gitkeep", | ||
| "required": false, | ||
| "description": "Placeholder for unit and integration tests" | ||
| } | ||
| ] | ||
| }, | ||
| "hermes": { | ||
| "emoji": "TG", | ||
| "category": "security", | ||
| "requires": { | ||
| "bins": [ | ||
| "node", | ||
| "python3" | ||
| ] | ||
| }, | ||
| "runtime": { | ||
| "required_env": [], | ||
| "optional_env": [ | ||
| "HERMES_TRAFFIC_GUARDIAN_HOME", | ||
| "HERMES_TRAFFIC_GUARDIAN_CONFIG", | ||
| "HERMES_TRAFFIC_GUARDIAN_MODE", | ||
| "HERMES_TRAFFIC_GUARDIAN_PROXY_URL", | ||
| "HERMES_TRAFFIC_GUARDIAN_CA_BUNDLE", | ||
| "HERMES_TRAFFIC_GUARDIAN_LOG_DIR", | ||
| "HERMES_TRAFFIC_GUARDIAN_MAX_SCAN_BYTES", | ||
| "HERMES_TRAFFIC_GUARDIAN_REDACT_SNIPPETS", | ||
| "HERMES_TRAFFIC_GUARDIAN_ATTESTATION_OUTPUT" | ||
| ] | ||
| }, | ||
| "capabilities": { | ||
| "runtime_traffic_monitoring": "spec_baseline", | ||
| "http_proxy_inspection": "planned", | ||
| "https_mitm_inspection": "planned_optional", | ||
| "egress_exfiltration_detection": "planned", | ||
| "inbound_injection_detection": "planned", | ||
| "attestation_export": "planned", | ||
| "blocking": "future_version" | ||
| }, | ||
| "execution": { | ||
| "always": false, | ||
| "persistence": "Spec baseline only. Builders must keep monitoring opt-in and scheduler-free unless an operator explicitly applies one.", | ||
| "network_egress": "Future runtime will proxy operator-scoped Hermes traffic. No runtime network behavior is implemented in v0.0.1." | ||
| }, | ||
| "operator_review": [ | ||
| "Do not merge proxy runtime into hermes-attestation-guardian.", | ||
| "Export traffic-monitor status for hermes-attestation-guardian to attest, but keep runtime ownership in this skill.", | ||
| "Do not install a system-wide CA automatically.", | ||
| "Default to detect-and-log mode; blocking is out of scope for v0.0.1 implementation.", | ||
| "Redact secret snippets before writing logs or attestation-linked summaries." | ||
| ], | ||
| "triggers": [ | ||
| "hermes traffic guardian", | ||
| "hermes traffic monitoring", | ||
| "monitor hermes egress", | ||
| "inspect hermes http traffic", | ||
| "attest hermes traffic monitor" | ||
| ] | ||
| } | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
|
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,8 @@ | ||
| # Changelog | ||
|
|
||
| ## [0.0.1-beta1] - 2026-05-10 | ||
|
|
||
| - Added baseline skill metadata, frontmatter, and implementation specification. | ||
| - Reserved folder structure for NanoClaw host services, MCP tools, detector code, and tests. | ||
| - Beta release notes: this release is a scaffold/spec baseline and does not yet ship active runtime proxy interception. | ||
| - Beta release notes: host-service and MCP contracts are defined, but detection/enforcement behavior is not active by default. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,18 @@ | ||
| # NanoClaw Traffic Guardian | ||
|
|
||
| Baseline skill for NanoClaw runtime traffic monitoring. | ||
|
|
||
| This package is intentionally a spec scaffold. Builders should add the NanoClaw-specific host-service, IPC, and MCP implementation here while preserving the safety contract in `SKILL.md` and `SPEC.md`. | ||
|
|
||
| ## Intended Capability | ||
|
|
||
| - detect outbound secret exfiltration in NanoClaw host-managed traffic | ||
| - detect inbound command-injection and tool-abuse payloads | ||
| - keep CA private key material outside the container | ||
| - expose redacted status/findings through MCP tools | ||
| - provide explicit host-side lifecycle controls | ||
|
|
||
| ## Builder Notes | ||
|
|
||
| Follow the existing `clawsec-nanoclaw` pattern: host services own privileged operations, while MCP tools expose bounded requests and redacted responses. | ||
|
|
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should we update the release catalog builder to read the new
hermes/nanoclaw/picoclawmetadata instead of.openclaw.emoji/.openclaw.category, since this file lacksopenclawand chained jq lookup will fail duringpublic/skills/index.jsongeneration? (Also consider normalizing the builder or adding anopenclawalias to satisfySkillMetadata’s stringemoji/categoryshape.)Finding type:
Breaking Changes| Severity: 🔴 HighWant Baz to fix this for you? Activate Fixer
Other fix methods
Prompt for AI Agents: