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.
- package/CHANGELOG.md +20 -3
- package/README.md +52 -18
- package/dist/classifiers/injectionClassifier.d.ts +26 -0
- package/dist/classifiers/injectionClassifier.js +38 -0
- package/dist/classifiers/injectionClassifier.js.map +1 -0
- package/dist/cli/index.d.ts +1 -0
- package/dist/cli/index.js +27 -2
- package/dist/cli/index.js.map +1 -1
- package/dist/core/audit.js.map +1 -1
- package/dist/core/engine.d.ts +11 -0
- package/dist/core/engine.js +63 -3
- package/dist/core/engine.js.map +1 -1
- package/dist/core/policy.d.ts +86 -261
- package/dist/core/policy.js +18 -0
- package/dist/core/policy.js.map +1 -1
- package/dist/core/types.d.ts +32 -0
- package/dist/core/types.js.map +1 -1
- package/dist/demo/mockAgent.js.map +1 -1
- package/dist/index.d.ts +3 -0
- package/dist/index.js +3 -0
- package/dist/index.js.map +1 -1
- package/dist/scanners/injection.js +19 -1
- package/dist/scanners/injection.js.map +1 -1
- package/dist/server/serve.d.ts +39 -0
- package/dist/server/serve.js +140 -0
- package/dist/server/serve.js.map +1 -0
- package/dist/util/homoglyphs.d.ts +31 -0
- package/dist/util/homoglyphs.js +56 -0
- package/dist/util/homoglyphs.js.map +1 -0
- package/dist/util/paths.js.map +1 -1
- package/docs/ARCHITECTURE.md +23 -23
- package/docs/COMPARISON.md +28 -28
- package/docs/POLICY_REFERENCE.md +34 -10
- package/docs/REQUIREMENTS.md +11 -11
- package/docs/ROADMAP.md +26 -23
- package/docs/THREAT_MODEL.md +14 -14
- package/package.json +5 -5
package/docs/REQUIREMENTS.md
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
|
-
# ActionWall
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
80
|
-
- **Security/platform engineer
|
|
81
|
-
- **Operator/agent owner
|
|
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
|
|
1
|
+
# ActionWall: Roadmap
|
|
2
2
|
|
|
3
|
-
|
|
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
|
-
-
|
|
9
|
-
|
|
10
|
-
## v0.2 — integration depth
|
|
11
|
+
- Presets: default / strict / readonly
|
|
11
12
|
|
|
12
|
-
|
|
13
|
-
-
|
|
14
|
-
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
25
|
-
|
|
26
|
-
- [ ]
|
|
27
|
-
- [ ]
|
|
28
|
-
- [ ]
|
|
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
|
-
##
|
|
30
|
+
## Exploring
|
|
32
31
|
|
|
33
|
-
- [ ]
|
|
34
|
-
- [ ]
|
|
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
|
package/docs/THREAT_MODEL.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# ActionWall
|
|
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
|
|
18
|
-
2. **Compromised dependency/tool
|
|
19
|
-
3. **Confused/degraded agent
|
|
20
|
-
4. **Local attacker with user-level code execution
|
|
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
|
|
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
|
|
71
|
-
- **L2
|
|
72
|
-
- **L3
|
|
73
|
-
- **L4
|
|
74
|
-
- **L5
|
|
75
|
-
- **L6
|
|
76
|
-
- **L7
|
|
77
|
-
- **L8
|
|
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.
|
|
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": "^
|
|
59
|
+
"zod": "^4.6.7"
|
|
60
60
|
},
|
|
61
61
|
"devDependencies": {
|
|
62
|
-
"@types/node": "^
|
|
62
|
+
"@types/node": "^26.6.5",
|
|
63
63
|
"tsx": "^4.19.0",
|
|
64
|
-
"typescript": "^
|
|
65
|
-
"vitest": "^
|
|
64
|
+
"typescript": "^7.0.2",
|
|
65
|
+
"vitest": "^5.0.5"
|
|
66
66
|
}
|
|
67
67
|
}
|