actionwall 0.1.1 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,10 +1,10 @@
1
- # ActionWall — Requirements Specification
1
+ # ActionWall: Requirements Specification
2
2
 
3
3
  Version 1.0 · Status: implemented (v0.1.1) · Identified functional and non-functional requirements, each with acceptance criteria mapped to the test suite.
4
4
 
5
5
  ## 1. Problem statement
6
6
 
7
- AI agents execute tools autonomously: shell commands, file writes, HTTP requests, third-party APIs. A compromised prompt (prompt injection), a hallucinated action, or a bug can cause irreversible damage — deleted files, leaked credentials, SSRF into cloud infrastructure. Existing safeguards (model guardrails, provider "safety" layers) are probabilistic and sit *inside* the model. There is no deterministic, auditable, policy-driven control point between the agent and its tools.
7
+ AI agents execute tools autonomously: shell commands, file writes, HTTP requests, third-party APIs. A compromised prompt (prompt injection), a hallucinated action, or a bug can cause irreversible damage: deleted files, leaked credentials, SSRF into cloud infrastructure. Existing safeguards (model guardrails, provider "safety" layers) are probabilistic and sit *inside* the model. There is no deterministic, auditable, policy-driven control point between the agent and its tools.
8
8
 
9
9
  ## 2. Goals & non-goals
10
10
 
@@ -16,7 +16,7 @@ AI agents execute tools autonomously: shell commands, file writes, HTTP requests
16
16
  - G5: Zero network calls and zero command execution inside the firewall itself.
17
17
 
18
18
  **Non-goals (v1)**
19
- - Running as a network proxy (planned — see ROADMAP).
19
+ - Running as a network proxy (planned, see ROADMAP).
20
20
  - Stopping a *determined* adversary with arbitrary obfuscated payloads; ActionWall raises the floor and adds auditability, it is not a sandbox (see THREAT_MODEL).
21
21
  - Replacing OS-level sandboxing (containers, users, seccomp). It complements them.
22
22
 
@@ -26,7 +26,7 @@ AI agents execute tools autonomously: shell commands, file writes, HTTP requests
26
26
 
27
27
  | ID | Requirement | Acceptance criteria |
28
28
  |---|---|---|
29
- | FR-1 | Engine accepts an Action `{tool, params, agentId, context}` and returns a Decision `{verdict, risk, findings[], summary, latencyMs}`. | `engine.test.ts` — clean action yields `ALLOW`, risk `LOW`, latency ≥ 0. |
29
+ | FR-1 | Engine accepts an Action `{tool, params, agentId, context}` and returns a Decision `{verdict, risk, findings[], summary, latencyMs}`. | `engine.test.ts`: clean action yields `ALLOW`, risk `LOW`, latency ≥ 0. |
30
30
  | FR-2 | Verdicts are exactly `ALLOW`, `BLOCK`, `ASK_HUMAN`. | All tests assert one of three values. |
31
31
  | FR-3 | Severity levels are `LOW < MEDIUM < HIGH < CRITICAL`; the decision's risk is the worst finding. | FR-1 + scanner tests. |
32
32
  | FR-4 | Policy maps severities → verdicts (`risk_thresholds.block` / `.ask`). | `engine.test.ts` custom thresholds: HIGH→ASK when configured. |
@@ -39,9 +39,9 @@ AI agents execute tools autonomously: shell commands, file writes, HTTP requests
39
39
  |---|---|---|---|
40
40
  | FR-7 | toolPermissions | Allow/deny lists with `*` wildcards, global or per-agent; deny wins over allow; deny-by-default mode. | `toolPermissions.test.ts`. |
41
41
  | FR-8 | commandRisk | Tokenize shell commands (quote-aware, chain/pipeline aware) without executing; detect destructive FS ops, privilege escalation, pipe-to-shell, reverse shells, fork bombs, raw device writes, env dumps, obfuscation, custom regex patterns. | `commandRisk.test.ts` (13 cases). |
42
- | FR-9 | commandRisk | **Bulk-delete rule:** expand `rm` targets against the real filesystem (read-only) and block when the count exceeds `file_policy.max_bulk_delete`. | `commandRisk.test.ts` — 12 files with limit 10 → CRITICAL, evidence names the count. |
42
+ | FR-9 | commandRisk | **Bulk-delete rule:** expand `rm` targets against the real filesystem (read-only) and block when the count exceeds `file_policy.max_bulk_delete`. | `commandRisk.test.ts`: 12 files with limit 10 → CRITICAL, evidence names the count. |
43
43
  | FR-10 | filePolicy | Protected-path rules (`deny` / `readonly` / `allow`, first match wins) applied to `file.*` tools **and** file-touching shell commands; workspace containment for reads/writes/deletes. | `filePolicy.test.ts`. |
44
- | FR-11 | secrets | Detect known credential formats + credential assignments (with placeholder filtering) + high-entropy tokens in tool args; never emit the raw secret in findings. | `secrets.test.ts` — AWS/GitHub/OpenAI/private-key/JWT cases; redaction assertions. |
44
+ | FR-11 | secrets | Detect known credential formats + credential assignments (with placeholder filtering) + high-entropy tokens in tool args; never emit the raw secret in findings. | `secrets.test.ts`: AWS/GitHub/OpenAI/private-key/JWT cases; redaction assertions. |
45
45
  | FR-12 | urlPolicy | Scheme allowlist, domain allow/deny lists with wildcards, private-network & cloud-metadata SSRF guard; applies to web tools and to URLs inside shell commands. | `urlPolicy.test.ts`. |
46
46
  | FR-13 | injection | Heuristic detection of instruction overrides, fake system markers, prompt-extraction, markdown-image exfiltration, hidden characters, in `toolOutput` and `userPrompt`; N distinct patterns escalate MEDIUM→HIGH. | `injection.test.ts`. |
47
47
 
@@ -49,7 +49,7 @@ AI agents execute tools autonomously: shell commands, file writes, HTTP requests
49
49
 
50
50
  | ID | Requirement | Acceptance criteria |
51
51
  |---|---|---|
52
- | FR-14 | Every decision (including ALLOW, configurable) is appended to daily JSONL files with action params, verdict, risk, findings. | `cli.test.ts` — check writes to `.actionwall/audit/`. |
52
+ | FR-14 | Every decision (including ALLOW, configurable) is appended to daily JSONL files with action params, verdict, risk, findings. | `cli.test.ts`: check writes to `.actionwall/audit/`. |
53
53
  | FR-15 | Records are hash-chained (SHA-256 over prev hash + record); `verify` re-walks the chain and pinpoints the first broken entry. | `audit.test.ts` + `cli.test.ts` tamper case. |
54
54
  | FR-16 | Secrets in logged params are redacted. | `audit.test.ts`. |
55
55
 
@@ -58,7 +58,7 @@ AI agents execute tools autonomously: shell commands, file writes, HTTP requests
58
58
  | ID | Requirement | Acceptance criteria |
59
59
  |---|---|---|
60
60
  | FR-17 | `check <command-or-json>` with `--tool/--params/--context/--agent/--policy/--json/--no-log`. | `cli.test.ts`. |
61
- | FR-18 | Exit codes: 0 allow, 1 block, 3 ask-human, 2 error — CI usable. | `cli.test.ts`. |
61
+ | FR-18 | Exit codes: 0 allow, 1 block, 3 ask-human, 2 error. CI usable. | `cli.test.ts`. |
62
62
  | FR-19 | `validate`, `log [--last N] [--verify]`, `demo`. | `cli.test.ts`. |
63
63
 
64
64
  ## 4. Non-functional requirements
@@ -76,9 +76,9 @@ AI agents execute tools autonomously: shell commands, file writes, HTTP requests
76
76
 
77
77
  ## 5. Personas
78
78
 
79
- - **Agent developer** — integrates ActionWall into a tool loop; wants `guard()` and clear errors.
80
- - **Security/platform engineer** — writes policies and reviews the audit log; wants `validate` and `log --verify`.
81
- - **Operator/agent owner** — receives ASK_HUMAN escalations and approves or denies.
79
+ - **Agent developer**: integrates ActionWall into a tool loop; wants `guard()` and clear errors.
80
+ - **Security/platform engineer**: writes policies and reviews the audit log; wants `validate` and `log --verify`.
81
+ - **Operator/agent owner**: receives ASK_HUMAN escalations and approves or denies.
82
82
 
83
83
  ## 6. Acceptance scenario (product pitch parity)
84
84
 
package/docs/ROADMAP.md CHANGED
@@ -1,36 +1,39 @@
1
- # ActionWall — Roadmap
1
+ # ActionWall: Roadmap
2
2
 
3
- ## v0.1 (current)
3
+ Milestones record what shipped. Versions snapshot the work at release time, so unfinished items simply carry forward.
4
4
 
5
+ ## Shipped
6
+
7
+ ### v0.1
5
8
  - Core engine: 6 scanners, YAML/JSON policies with zod validation, fail-closed defaults
6
9
  - CLI: check / validate / log / demo, CI-friendly exit codes
7
10
  - Hash-chained JSONL audit log with `--verify`
8
- - 76 tests; presets: default / strict / readonly
9
-
10
- ## v0.2 — integration depth
11
+ - Presets: default / strict / readonly
11
12
 
12
- - [ ] **HTTP service mode** (`actionwall serve`): POST /v1/check, per-tenant policies, p99 < 5 ms budget
13
- - [ ] **MCP guard**: run ActionWall as an MCP gateway/proxy so Claude Desktop & friends are protected without code changes
14
- - [ ] Official middleware packages: OpenAI tool-calling, Anthropic tool-use, LangChain/LangGraph, Vercel AI SDK
15
- - [ ] Async audit writer (batched, back-pressured) for high-throughput service mode
13
+ ### v0.2
14
+ - HTTP service mode (`actionwall serve`): POST /v1/check with `x-actionwall-verdict` / `x-actionwall-risk` headers, GET /healthz, per-tenant policies via a tenants file
15
+ - Dependency refresh: commander 15, zod 4, vitest 5, typescript 7, @types/node 26
16
16
 
17
- ## v0.3 — smarter detection (shadow-first)
17
+ ### v0.3 (current)
18
+ - Rule tuning: `rules.severities` overrides and `rules.exceptions` evidence-scoped suppression
19
+ - Homoglyph and mixed-script evasion detection in the injection scanner
20
+ - Pluggable injection classifier with shadow and enforce modes (keyword baseline included)
18
21
 
19
- - [ ] Pluggable ML classifier for prompt injection (returns standard Findings; runs in shadow mode first)
20
- - [ ] Per-scanner exceptions/allowlists (`*.pem` allow for a build agent)
21
- - [ ] Configurable rule severities (user-tunable rule table in policy)
22
- - [ ] Homoglyph/confusable detection with per-locale opt-in
22
+ ## Next
23
23
 
24
- ## v0.4 — operations & trust
25
-
26
- - [ ] Real approvals workflow for ASK_HUMAN (queue, TTL, auto-deny, Slack/webhook)
27
- - [ ] Remote audit sink (S3 Object Lock / syslog) + periodic signed Merkle checkpoints — tamper-*proof* rather than tamper-evident
28
- - [ ] `actionwall replay` — re-run past actions under a new policy ("what would have been blocked?")
29
- - [ ] Metrics endpoint (Prometheus): decisions, verdicts, rule hits, latency histograms
24
+ - [ ] **MCP guard**: run ActionWall as an MCP gateway/proxy so Claude Desktop and friends are protected without code changes
25
+ - [ ] Official middleware packages: OpenAI tool-calling, Anthropic tool-use, LangChain/LangGraph, Vercel AI SDK
26
+ - [ ] Async audit writer (batched, back-pressured) for high-throughput service mode
27
+ - [ ] Approvals workflow for ASK_HUMAN (queue, TTL, auto-deny, Slack/webhook)
28
+ - [ ] Remote audit sink (S3 Object Lock / syslog) + periodic signed Merkle checkpoints
30
29
 
31
- ## v1.0 — hardening
30
+ ## Exploring
32
31
 
33
- - [ ] Differential shell parsing (exchange the tokenizer for a battle-tested parser behind the same interface)
34
- - [ ] Policy inheritance & org/team composition
32
+ - [ ] `actionwall replay`: re-run past actions under a new policy ("what would have been blocked?")
33
+ - [ ] Metrics endpoint (Prometheus)
34
+ - [ ] Homoglyph coverage expansion: fuller Unicode confusables tables
35
+ - [ ] Real-model benchmarking for the injection classifier
36
+ - [ ] Differential shell parsing (exchange the tokenizer behind the same interface)
37
+ - [ ] Policy inheritance and org/team composition
35
38
  - [ ] Fuzzing harness for the tokenizer and glob walker
36
39
  - [ ] WASM build for browser/edge agent runtimes
@@ -1,4 +1,4 @@
1
- # ActionWall — Threat Model
1
+ # ActionWall: Threat Model
2
2
 
3
3
  Scope: an AI agent (LLM-driven) running on a developer workstation or a server, executing tools autonomously. ActionWall is the enforcement point between the agent and its tools.
4
4
 
@@ -14,10 +14,10 @@ Scope: an AI agent (LLM-driven) running on a developer workstation or a server,
14
14
 
15
15
  ## 2. Adversaries
16
16
 
17
- 1. **Remote attacker via content** — crafts a web page, file, issue, or email whose *content* the agent will read; goal: prompt-inject the agent into harmful actions (OWASP LLM01).
18
- 2. **Compromised dependency/tool** — an MCP server or npm package the agent uses misbehaves or exfiltrates.
19
- 3. **Confused/degraded agent** — not malicious, just wrong: hallucinated paths, over-broad globs, wrong environment (prod vs dev).
20
- 4. **Local attacker with user-level code execution** — can already do most damage directly; ActionWall's audit log still raises forensics cost (but see Limitations L7).
17
+ 1. **Remote attacker via content**: crafts a web page, file, issue, or email whose *content* the agent will read; goal: prompt-inject the agent into harmful actions (OWASP LLM01).
18
+ 2. **Compromised dependency/tool**: an MCP server or npm package the agent uses misbehaves or exfiltrates.
19
+ 3. **Confused/degraded agent**: not malicious, just wrong: hallucinated paths, over-broad globs, wrong environment (prod vs dev).
20
+ 4. **Local attacker with user-level code execution**: can already do most damage directly; ActionWall's audit log still raises forensics cost (but see Limitations L7).
21
21
 
22
22
  ## 3. Attack scenarios → controls
23
23
 
@@ -54,7 +54,7 @@ Scope: an AI agent (LLM-driven) running on a developer workstation or a server,
54
54
 
55
55
  | OWASP item | ActionWall coverage |
56
56
  |---|---|
57
- | LLM01 Prompt Injection | injection scanner (heuristics) + the entire deny/confirm pipeline; **detection ≠ prevention** — see L1 |
57
+ | LLM01 Prompt Injection | injection scanner (heuristics) + the entire deny/confirm pipeline; **detection ≠ prevention**, see L1 |
58
58
  | LLM02 Sensitive Information Disclosure | secrets scanner, protected paths, redacted audit |
59
59
  | LLM03 Supply Chain | tool permission lists; a compromised tool still runs *inside* policy |
60
60
  | LLM04 Data & Model Poisoning | out of scope (training-time) |
@@ -67,14 +67,14 @@ Scope: an AI agent (LLM-driven) running on a developer workstation or a server,
67
67
 
68
68
  ## 6. Honest limitations
69
69
 
70
- - **L1 — Heuristics are bypassable.** Paraphrased, multilingual, or steganographic injections will pass pattern matching. ActionWall's answer is *defense in depth*: even a successful injection still has to get the resulting *action* past the command/file/URL/secret scanners. Planned: pluggable LLM classifier.
71
- - **L2 — Shell emulation is bounded.** The tokenizer doesn't model expansion semantics (`$IFS`, brace expansion, aliases, heredocs). Residual ambiguity is handled conservatively (substitution/eval rules), not perfectly.
72
- - **L3 — Counting is bounded, not exact.** The bulk-delete walk caps at 5000 entries; beyond the cap it's a lower bound (reported as "5000+"), which is fine — the rule only needs "is it over 10".
73
- - **L4 — Race conditions.** A file could appear between counting and deletion. ActionWall is a gate, not a transactional FS layer.
74
- - **L5 — TOCTOU on decisions.** What the agent does *after* an ALLOW (e.g. writes a script, then a later action runs it) is only caught when that later action is checked.
75
- - **L6 — No OS-level guarantees.** This is policy enforcement in process. Pair with containers, users, seccomp for hard isolation.
76
- - **L7 — Audit chain is tamper-evident, not tamper-proof.** A full-file rewrite with recomputed hashes is detectable only with an external anchor (remote sink / signing) — ROADMAP.
77
- - **L8 — Unicode tricks.** Zero-width characters are flagged; homoglyph substitution is not (too noisy for a default rule).
70
+ - **L1: Heuristics are bypassable.** Paraphrased, multilingual, or steganographic injections will pass pattern matching. ActionWall's answer is *defense in depth*: even a successful injection still has to get the resulting *action* past the command/file/URL/secret scanners. Planned: pluggable LLM classifier.
71
+ - **L2: Shell emulation is bounded.** The tokenizer doesn't model expansion semantics (`$IFS`, brace expansion, aliases, heredocs). Residual ambiguity is handled conservatively (substitution/eval rules), not perfectly.
72
+ - **L3: Counting is bounded, not exact.** The bulk-delete walk caps at 5000 entries; beyond the cap it's a lower bound (reported as "5000+"), which is fine, since the rule only needs "is it over 10".
73
+ - **L4: Race conditions.** A file could appear between counting and deletion. ActionWall is a gate, not a transactional FS layer.
74
+ - **L5: TOCTOU on decisions.** What the agent does *after* an ALLOW (e.g. writes a script, then a later action runs it) is only caught when that later action is checked.
75
+ - **L6: No OS-level guarantees.** This is policy enforcement in process. Pair with containers, users, seccomp for hard isolation.
76
+ - **L7: Audit chain is tamper-evident, not tamper-proof.** A full-file rewrite with recomputed hashes is detectable only with an external anchor (remote sink / signing); see ROADMAP.
77
+ - **L8: Unicode tricks.** Zero-width characters are flagged; homoglyph substitution is not (too noisy for a default rule).
78
78
 
79
79
  ## 7. Deployment guidance (defense in depth)
80
80
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "actionwall",
3
- "version": "0.1.1",
3
+ "version": "0.3.0",
4
4
  "description": "Security firewall for AI agents — inspect every tool call, command, file access and HTTP request against a policy before it runs.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -56,12 +56,12 @@
56
56
  "dependencies": {
57
57
  "commander": "^15.0.0",
58
58
  "yaml": "^2.6.0",
59
- "zod": "^3.24.1"
59
+ "zod": "^4.6.7"
60
60
  },
61
61
  "devDependencies": {
62
- "@types/node": "^22.10.0",
62
+ "@types/node": "^26.6.5",
63
63
  "tsx": "^4.19.0",
64
- "typescript": "^5.7.0",
65
- "vitest": "^3.0.0"
64
+ "typescript": "^7.0.2",
65
+ "vitest": "^5.0.5"
66
66
  }
67
67
  }