actionwall 0.1.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.
Files changed (70) hide show
  1. package/CHANGELOG.md +16 -0
  2. package/LICENSE +21 -0
  3. package/README.md +204 -0
  4. package/dist/cli/format.d.ts +26 -0
  5. package/dist/cli/format.js +74 -0
  6. package/dist/cli/format.js.map +1 -0
  7. package/dist/cli/index.d.ts +12 -0
  8. package/dist/cli/index.js +156 -0
  9. package/dist/cli/index.js.map +1 -0
  10. package/dist/core/audit.d.ts +61 -0
  11. package/dist/core/audit.js +126 -0
  12. package/dist/core/audit.js.map +1 -0
  13. package/dist/core/engine.d.ts +48 -0
  14. package/dist/core/engine.js +140 -0
  15. package/dist/core/engine.js.map +1 -0
  16. package/dist/core/policy.d.ts +307 -0
  17. package/dist/core/policy.js +138 -0
  18. package/dist/core/policy.js.map +1 -0
  19. package/dist/core/types.d.ts +147 -0
  20. package/dist/core/types.js +24 -0
  21. package/dist/core/types.js.map +1 -0
  22. package/dist/demo/mockAgent.d.ts +33 -0
  23. package/dist/demo/mockAgent.js +130 -0
  24. package/dist/demo/mockAgent.js.map +1 -0
  25. package/dist/index.d.ts +27 -0
  26. package/dist/index.js +26 -0
  27. package/dist/index.js.map +1 -0
  28. package/dist/scanners/commandRisk.d.ts +20 -0
  29. package/dist/scanners/commandRisk.js +335 -0
  30. package/dist/scanners/commandRisk.js.map +1 -0
  31. package/dist/scanners/filePolicy.d.ts +15 -0
  32. package/dist/scanners/filePolicy.js +165 -0
  33. package/dist/scanners/filePolicy.js.map +1 -0
  34. package/dist/scanners/injection.d.ts +15 -0
  35. package/dist/scanners/injection.js +111 -0
  36. package/dist/scanners/injection.js.map +1 -0
  37. package/dist/scanners/secrets.d.ts +12 -0
  38. package/dist/scanners/secrets.js +102 -0
  39. package/dist/scanners/secrets.js.map +1 -0
  40. package/dist/scanners/toolPermissions.d.ts +7 -0
  41. package/dist/scanners/toolPermissions.js +60 -0
  42. package/dist/scanners/toolPermissions.js.map +1 -0
  43. package/dist/scanners/urlPolicy.d.ts +16 -0
  44. package/dist/scanners/urlPolicy.js +176 -0
  45. package/dist/scanners/urlPolicy.js.map +1 -0
  46. package/dist/util/ansi.d.ts +13 -0
  47. package/dist/util/ansi.js +20 -0
  48. package/dist/util/ansi.js.map +1 -0
  49. package/dist/util/entropy.d.ts +6 -0
  50. package/dist/util/entropy.js +20 -0
  51. package/dist/util/entropy.js.map +1 -0
  52. package/dist/util/paths.d.ts +43 -0
  53. package/dist/util/paths.js +192 -0
  54. package/dist/util/paths.js.map +1 -0
  55. package/dist/util/secretPatterns.d.ts +19 -0
  56. package/dist/util/secretPatterns.js +93 -0
  57. package/dist/util/secretPatterns.js.map +1 -0
  58. package/dist/util/shell.d.ts +31 -0
  59. package/dist/util/shell.js +154 -0
  60. package/dist/util/shell.js.map +1 -0
  61. package/docs/ARCHITECTURE.md +115 -0
  62. package/docs/COMPARISON.md +99 -0
  63. package/docs/POLICY_REFERENCE.md +126 -0
  64. package/docs/REQUIREMENTS.md +87 -0
  65. package/docs/ROADMAP.md +36 -0
  66. package/docs/THREAT_MODEL.md +88 -0
  67. package/package.json +67 -0
  68. package/policies/default.yaml +70 -0
  69. package/policies/readonly.yaml +58 -0
  70. package/policies/strict.yaml +75 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,16 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented here.
4
+ Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
5
+
6
+ ## [0.1.0] — 2026-09-14
7
+
8
+ ### Added
9
+ - Core decision engine: `(Action, Policy) → ALLOW / BLOCK / ASK_HUMAN` with severity aggregation and fail-closed defaults.
10
+ - Six scanners: toolPermissions (wildcards, deny-by-default, per-agent overrides), commandRisk (quote-aware shell analysis, bulk-delete counting, pipe-to-shell, reverse shells, privilege escalation, obfuscation), filePolicy (protected paths, workspace containment, traversal-proof matching), secrets (signature + entropy detection with redaction), urlPolicy (schemes, domain lists, SSRF/metadata guard), injection (override/exfil/hidden-character heuristics).
11
+ - YAML/JSON policy loader with zod validation and safe defaults; presets `default`, `strict`, `readonly`.
12
+ - Tamper-evident audit log: daily JSONL files, SHA-256 hash chain, `--verify`, automatic secret redaction.
13
+ - CLI: `check`, `validate`, `log`, `demo` with CI-friendly exit codes (0/1/3/2).
14
+ - Scripted demo agent (`actionwall demo`) — 9 actions: 3 allowed, 1 escalated, 5 blocked.
15
+ - 76 unit/integration tests (vitest); GitHub Actions CI on Node 20/22/24.
16
+ - Documentation: README, REQUIREMENTS, ARCHITECTURE, THREAT_MODEL, POLICY_REFERENCE, COMPARISON, ROADMAP.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 ActionWall contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,204 @@
1
+ <p align="center">
2
+ <img src="docs/assets/banner.svg" alt="ActionWall — Security Firewall for AI Agents" width="830">
3
+ </p>
4
+
5
+ <p align="center">
6
+ <a href="https://github.com/uzairr-arif/actionwall/actions/workflows/ci.yml"><img src="https://github.com/uzairr-arif/actionwall/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
7
+ <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT license"></a>
8
+ <img src="https://img.shields.io/badge/node-%3E%3D20-blue.svg" alt="Node ≥ 20">
9
+ <img src="https://img.shields.io/badge/tests-76%20passing-brightgreen.svg" alt="76 tests passing">
10
+ </p>
11
+
12
+ **ActionWall is a policy firewall that sits between an AI agent and its tools.** Every tool call, shell command, file access and HTTP request an agent wants to make is inspected *before it runs* — scored against a YAML policy you control — and either **allowed**, **blocked**, or **escalated to a human**, with a tamper-evident audit log of everything.
13
+
14
+ ```
15
+ AI Agent
16
+ ↓
17
+ ActionWall
18
+ ├── Tool permission check
19
+ ├── Command risk analysis
20
+ ├── Secret detection
21
+ ├── URL / domain policy (incl. SSRF guard)
22
+ ├── File access policy
23
+ ├── Prompt-injection detection
24
+ └── Action logging (hash-chained)
25
+ ↓
26
+ External tools / Internet
27
+ ```
28
+
29
+ > **Why this exists:** agents can touch files, terminals, credentials and the internet. One compromised prompt or one over-eager tool call can delete a project, leak an API key, or fetch cloud instance metadata. ActionWall makes those failures *policy decisions*, not surprises.
30
+
31
+ ---
32
+
33
+ ## The 30-second demo
34
+
35
+ An agent wants to clean up its project directory:
36
+
37
+ ```bash
38
+ $ actionwall check "rm -rf /project/*"
39
+ ```
40
+
41
+ ```
42
+ 🔴 BLOCKED — Destructive filesystem operation
43
+ Tool: shell · Agent: cli-agent · Risk: CRITICAL · 3.2ms
44
+ Findings:
45
+ 🔴 [CMD-RM-BULK-DELETE] Destructive filesystem operation (commandRisk)
46
+ rm would delete 12 files; policy allows at most 10 automatic deletions
47
+ (file_policy.max_bulk_delete).
48
+ ```
49
+
50
+ **Reason:** destructive filesystem operation. **Policy:** *the agent is not allowed to delete more than 10 files automatically* — the firewall actually counted the files the glob would remove before letting anything run.
51
+
52
+ See it live with a full scripted agent (9 actions — 3 allowed, 1 escalated to a human, 5 blocked):
53
+
54
+ ```bash
55
+ npx tsx src/cli/index.ts demo # or: npm run demo
56
+ ```
57
+
58
+ ---
59
+
60
+ ## Quickstart
61
+
62
+ ```bash
63
+ npm install
64
+ npm run build && npm test # 76 tests
65
+ npx tsx src/cli/index.ts check "sudo chmod 777 /etc/hosts" --no-log
66
+ ```
67
+
68
+ **Installation:** the project currently installs from source (clone → `npm install` → `npm run build`). An npm package release is planned — the package is already publish-ready (bin, exports, type declarations). See [docs/COMPARISON.md](docs/COMPARISON.md) for how ActionWall relates to Llama Guard, NeMo Guardrails, Agent-Wall and other tools in this space.
69
+
70
+ ### Use it from Node
71
+
72
+ ```ts
73
+ import { ShieldEngine, loadPolicy, makeAction, ActionBlockedError } from "./src/index.js";
74
+
75
+ const engine = new ShieldEngine(loadPolicy("policies/default.yaml"));
76
+
77
+ // Inspect and decide:
78
+ const decision = engine.check(
79
+ makeAction({ tool: "shell", params: { command: "rm -rf build/*" }, agentId: "my-agent" })
80
+ );
81
+ if (decision.verdict === "BLOCK") console.log("⛔", decision.summary);
82
+
83
+ // Or throw-on-block integration for agent loops:
84
+ try {
85
+ engine.guard(makeAction({ tool: "http.request", params: { url: "https://api.github.com" } }));
86
+ } catch (e) {
87
+ if (e instanceof ActionBlockedError) console.log(e.decision.findings);
88
+ }
89
+ ```
90
+
91
+ Every action is a plain object, so this wraps **any** agent framework — you call `engine.check()` (or the `guard()` convenience) right before your tool executor runs. See [examples/guarded-agent.ts](examples/guarded-agent.ts).
92
+
93
+ ### CLI
94
+
95
+ | Command | Purpose |
96
+ |---|---|
97
+ | `actionwall check "cmd"` | Check a shell command (or a JSON action) against policy. Exit codes: `0` allow, `1` block, `3` ask-human, `2` error. |
98
+ | `actionwall validate --policy p.yaml` | Validate a policy file. |
99
+ | `actionwall log --last 10` | Show recent audit entries. |
100
+ | `actionwall log --verify` | Verify the audit log's SHA-256 hash chain. |
101
+ | `actionwall demo` | Run the scripted protected agent end-to-end. |
102
+
103
+ ---
104
+
105
+ ## What the scanners catch
106
+
107
+ | Scanner | Example catches | Default verdict |
108
+ |---|---|---|
109
+ | **Tool permissions** | tool on deny-list, deny-by-default allowlist violations | BLOCK / ASK |
110
+ | **Command risk** | `rm -rf /`, `curl … \| sh`, reverse shells, fork bombs, `dd of=/dev/…`, `sudo`, `env` dumps, `eval`, bulk deletes > limit | BLOCK / ASK |
111
+ | **File access policy** | reads of `.env` / `~/.ssh/**`, writes to `/etc/**`, deletions outside the workspace, path traversal, bulk deletion | BLOCK |
112
+ | **Secret detection** | AWS/GitHub/OpenAI/Stripe/Slack tokens, private keys, JWTs, credential assignments, high-entropy unknown tokens — always **redacted** in logs | BLOCK |
113
+ | **URL / domain policy** | cloud metadata endpoints (`169.254.169.254`), localhost/private ranges (SSRF), deny-listed or non-allow-listed domains, `file://` scheme | BLOCK |
114
+ | **Prompt injection** | "ignore previous instructions", fake system markers, role overrides, markdown-image exfiltration, hidden zero-width characters | ASK / BLOCK |
115
+
116
+ Verdicts come from policy thresholds (`HIGH/CRITICAL → BLOCK`, `MEDIUM → ASK_HUMAN` by default) and the engine is **fail-closed**: if a scanner itself crashes, the action is blocked.
117
+
118
+ ## Policies
119
+
120
+ A policy is a small YAML file. Three presets ship in [`policies/`](policies/): `default.yaml` (balanced), `strict.yaml` (deny-by-default tools, egress allowlist), `readonly.yaml` (analysis agents that can't touch anything). Every field is documented in [docs/POLICY_REFERENCE.md](docs/POLICY_REFERENCE.md).
121
+
122
+ ```yaml
123
+ version: 1
124
+ name: my-team-policy
125
+ risk_thresholds: { block: [HIGH, CRITICAL], ask: [MEDIUM] }
126
+ tools:
127
+ default: deny
128
+ allow: [file.read, file.write, shell]
129
+ file_policy:
130
+ max_bulk_delete: 10
131
+ protected_paths:
132
+ - { path: "**/.env", permissions: [deny] }
133
+ url_policy:
134
+ allowed_schemes: [https]
135
+ block_private_networks: true
136
+ ```
137
+
138
+ ## Security model & limitations
139
+
140
+ Security claims should be specific, so here is the exact boundary (full detail in [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md)):
141
+
142
+ **What ActionWall protects against**
143
+ - Destructive filesystem operations — measured, not guessed: the firewall counts what a delete would actually remove
144
+ - Reads/writes/deletes of protected paths (`.env`, SSH keys, `.git/**`, `/etc/**` …) and access outside the workspace
145
+ - Dangerous shell patterns: pipe-to-shell, reverse shells, privilege escalation, fork bombs, raw device writes, obfuscated execution
146
+ - Credentials leaving through tool arguments (signature + entropy detection, redacted everywhere)
147
+ - SSRF: cloud metadata endpoints and private-network targets
148
+ - Excessive tool agency: allow/deny lists, deny-by-default, per-agent policies
149
+ - Specific classes of prompt-injection-*induced* actions, and common injection patterns in tool output
150
+
151
+ **What it does not protect against**
152
+ - Every possible prompt-injection technique (paraphrased/multilingual attacks can pass heuristics — the action scanners are the hard control, not the text scanner)
153
+ - A compromised host or agent runtime (pair with containers/OS sandboxing — ActionWall is a policy gate, not isolation)
154
+ - Vulnerabilities in your dependencies or in your own policy misconfiguration
155
+ - TOCTOU races: ActionWall is a gate at decision time, not a transactional filesystem layer
156
+
157
+ ## Audit log
158
+
159
+ Every decision is appended to `.actionwall/audit/audit-YYYY-MM-DD.jsonl` as a **hash-chained** record: each entry embeds the SHA-256 of the previous one, so editing or deleting history is detectable:
160
+
161
+ ```
162
+ $ actionwall log --verify
163
+ ✓ Chain intact — 13 entries verified in .actionwall/audit/audit-2026-09-14.jsonl
164
+ ```
165
+
166
+ Secrets are redacted before anything hits disk.
167
+
168
+ ## Documentation
169
+
170
+ | Doc | Contents |
171
+ |---|---|
172
+ | [docs/REQUIREMENTS.md](docs/REQUIREMENTS.md) | Functional & non-functional requirements (FR/NFR with acceptance criteria) |
173
+ | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Pipeline design, scanner contract, design decisions, extension guide |
174
+ | [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md) | STRIDE analysis, OWASP LLM Top-10 mapping, what's out of scope |
175
+ | [docs/COMPARISON.md](docs/COMPARISON.md) | Competitive landscape — how ActionWall differs from Llama Guard, NeMo Guardrails, Agent-Wall, sandboxes |
176
+ | [docs/POLICY_REFERENCE.md](docs/POLICY_REFERENCE.md) | Every policy field, with examples |
177
+ | [docs/ROADMAP.md](docs/ROADMAP.md) | What's next (MCP proxy, ML classifier, approvals workflow…) |
178
+
179
+ ## Project layout
180
+
181
+ ```
182
+ src/
183
+ ├── core/ types, engine (decision pipeline), policy loader, audit log
184
+ ├── scanners/ toolPermissions · commandRisk · filePolicy · secrets · urlPolicy · injection
185
+ ├── cli/ check · validate · log · demo + report formatting
186
+ ├── demo/ scripted mock agent used by `actionwall demo`
187
+ └── util/ safe shell tokenizer, bounded glob/FS counting, entropy, redaction
188
+ tests/ 76 unit & integration tests (vitest)
189
+ examples/ demo-block-rm-rf.ts · guarded-agent.ts (integration pattern)
190
+ policies/ default · strict · readonly
191
+ ```
192
+
193
+ ## Community
194
+
195
+ | | |
196
+ |---|---|
197
+ | **Contributing** | [CONTRIBUTING.md](CONTRIBUTING.md) — dev setup, ground rules, and how to add a scanner |
198
+ | **Security** | [SECURITY.md](SECURITY.md) — responsible disclosure (please don't open public issues for exploitable bypasses) |
199
+ | **Changelog** | [CHANGELOG.md](CHANGELOG.md) — Keep-a-Changelog format |
200
+ | **Roadmap** | [docs/ROADMAP.md](docs/ROADMAP.md) — HTTP service mode, MCP guard, ML classifier, approvals workflow |
201
+
202
+ ## License
203
+
204
+ MIT — see [LICENSE](LICENSE).
@@ -0,0 +1,26 @@
1
+ /**
2
+ * Human-facing rendering of decisions — the colored report style shown in the
3
+ * README. All functions return string arrays; callers decide how to print.
4
+ */
5
+ import { type Decision, type Verdict } from "../core/types.js";
6
+ import type { DemoStep } from "../demo/mockAgent.js";
7
+ /** Full report for `actionwall check`. */
8
+ export declare function formatDecision(decision: Decision, logDir?: string): string[];
9
+ /** One demo step: header, action preview, verdict, top findings. */
10
+ export declare function formatStep(index: number, total: number, step: DemoStep, decision: Decision): string[];
11
+ /** Pretty-print an audit entry (for `actionwall log`). */
12
+ export declare function formatAuditEntry(entry: {
13
+ seq: number;
14
+ timestamp: string;
15
+ hash: string;
16
+ decision: {
17
+ verdict: Verdict;
18
+ risk: string;
19
+ summary: string;
20
+ };
21
+ action: {
22
+ agentId: string;
23
+ tool: string;
24
+ params: string;
25
+ };
26
+ }): string[];
@@ -0,0 +1,74 @@
1
+ /**
2
+ * Human-facing rendering of decisions — the colored report style shown in the
3
+ * README. All functions return string arrays; callers decide how to print.
4
+ */
5
+ import { bold, cyan, dim, green, red, yellow } from "../util/ansi.js";
6
+ import { RISK_ICONS } from "../core/types.js";
7
+ const VERDICT_LABEL = {
8
+ ALLOW: "ALLOWED",
9
+ ASK_HUMAN: "ASK HUMAN",
10
+ BLOCK: "BLOCKED",
11
+ };
12
+ const VERDICT_COLOR = {
13
+ ALLOW: green,
14
+ ASK_HUMAN: yellow,
15
+ BLOCK: red,
16
+ };
17
+ function paramPreview(params, max = 90) {
18
+ let s = JSON.stringify(params);
19
+ if (s.length > max)
20
+ s = `${s.slice(0, max - 1)}…`;
21
+ return s;
22
+ }
23
+ /** Full report for `actionwall check`. */
24
+ export function formatDecision(decision, logDir) {
25
+ const color = VERDICT_COLOR[decision.verdict];
26
+ const icon = decision.verdict === "BLOCK" ? "🔴" : decision.verdict === "ASK_HUMAN" ? "🟠" : "🟢";
27
+ const lines = [];
28
+ lines.push(color(bold(`${icon} ${VERDICT_LABEL[decision.verdict]} — ${decision.summary}`)));
29
+ lines.push(dim(` Tool: ${decision.tool} · Agent: ${decision.agentId} · Risk: ${decision.risk} · ${decision.latencyMs}ms`));
30
+ if (decision.findings.length > 0) {
31
+ lines.push(` ${bold("Findings:")}`);
32
+ for (const f of decision.findings) {
33
+ lines.push(` ${RISK_ICONS[f.severity]} ${bold(`[${f.ruleId}]`)} ${f.title} ${dim(`(${f.scanner})`)}`);
34
+ lines.push(` ${f.reason}`);
35
+ if (f.policyRef)
36
+ lines.push(dim(` policy: ${f.policyRef}`));
37
+ if (f.evidence)
38
+ lines.push(dim(` evidence: ${f.evidence}`));
39
+ }
40
+ }
41
+ if (logDir) {
42
+ const day = decision.timestamp.slice(0, 10);
43
+ lines.push(dim(` Audit: ${logDir}/audit-${day}.jsonl`));
44
+ }
45
+ return lines;
46
+ }
47
+ /** One demo step: header, action preview, verdict, top findings. */
48
+ export function formatStep(index, total, step, decision) {
49
+ const lines = [];
50
+ const color = VERDICT_COLOR[decision.verdict];
51
+ const icon = decision.verdict === "BLOCK" ? "🔴" : decision.verdict === "ASK_HUMAN" ? "🟠" : "🟢";
52
+ lines.push("");
53
+ lines.push(bold(cyan(`▸ Step ${index}/${total}`)) + ` ${step.label}`);
54
+ lines.push(dim(` ${decision.tool} ${paramPreview(step.action.params)}`));
55
+ lines.push(color(` ${icon} ${VERDICT_LABEL[decision.verdict]}`) +
56
+ dim(` risk=${decision.risk} · ${decision.latencyMs}ms · ${decision.summary}`));
57
+ for (const f of decision.findings.slice(0, 3)) {
58
+ lines.push(` ${RISK_ICONS[f.severity]} ${bold(`[${f.ruleId}]`)} ${f.reason}`);
59
+ }
60
+ if (decision.findings.length > 3) {
61
+ lines.push(dim(` … and ${decision.findings.length - 3} more finding(s)`));
62
+ }
63
+ return lines;
64
+ }
65
+ /** Pretty-print an audit entry (for `actionwall log`). */
66
+ export function formatAuditEntry(entry) {
67
+ const color = VERDICT_COLOR[entry.decision.verdict];
68
+ const icon = entry.decision.verdict === "BLOCK" ? "🔴" : entry.decision.verdict === "ASK_HUMAN" ? "🟠" : "🟢";
69
+ return [
70
+ `${color(icon)} #${String(entry.seq).padStart(3, "0")} ${color(entry.decision.verdict.padEnd(9))} ${dim(entry.timestamp)} ${entry.decision.risk.padEnd(8)} ${entry.action.tool} ${dim(entry.action.agentId)}`,
71
+ ` ${entry.decision.summary} ${dim(`hash ${entry.hash.slice(0, 12)}…`)}`,
72
+ ];
73
+ }
74
+ //# sourceMappingURL=format.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/cli/format.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,12 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * ActionWall CLI.
4
+ *
5
+ * actionwall check "rm -rf /project/*" inspect an action before it runs
6
+ * actionwall validate --policy policies/default.yaml
7
+ * actionwall log [--last N] [--verify] read / verify the audit trail
8
+ * actionwall demo [--policy path] scripted agent protected live
9
+ *
10
+ * Exit codes: 0 allowed · 1 blocked · 3 needs human approval · 2 error
11
+ */
12
+ export declare function runCli(argv: string[]): Promise<number>;
@@ -0,0 +1,156 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * ActionWall CLI.
4
+ *
5
+ * actionwall check "rm -rf /project/*" inspect an action before it runs
6
+ * actionwall validate --policy policies/default.yaml
7
+ * actionwall log [--last N] [--verify] read / verify the audit trail
8
+ * actionwall demo [--policy path] scripted agent protected live
9
+ *
10
+ * Exit codes: 0 allowed · 1 blocked · 3 needs human approval · 2 error
11
+ */
12
+ import { Command } from "commander";
13
+ import { existsSync } from "node:fs";
14
+ import * as path from "node:path";
15
+ import { pathToFileURL } from "node:url";
16
+ import { ShieldEngine, loadPolicy, makeAction, AuditLogger } from "../index.js";
17
+ import { formatDecision, formatAuditEntry } from "./format.js";
18
+ import { runDemo } from "../demo/mockAgent.js";
19
+ import { bold, dim, green, red } from "../util/ansi.js";
20
+ const VERSION = "0.1.0";
21
+ /** Policy resolution order: explicit flag > ./actionwall.yaml > ./policies/default.yaml > built-in. */
22
+ function resolvePolicyPath(explicit) {
23
+ if (explicit)
24
+ return explicit;
25
+ return ["actionwall.yaml", "actionwall.yml", path.join("policies", "default.yaml")].find((c) => existsSync(c));
26
+ }
27
+ function buildAction(actionArg, opts) {
28
+ const extraParams = opts.params ? JSON.parse(opts.params) : {};
29
+ const context = opts.context ? JSON.parse(opts.context) : undefined;
30
+ if (actionArg.trim().startsWith("{")) {
31
+ // Full action JSON: {"tool": "...", "params": {...}, "context": {...}}
32
+ const parsed = JSON.parse(actionArg);
33
+ return makeAction({
34
+ tool: parsed.tool ?? opts.tool,
35
+ params: parsed.params ?? extraParams,
36
+ agentId: parsed.agentId ?? opts.agent,
37
+ context: parsed.context ?? context,
38
+ });
39
+ }
40
+ // Plain shell command.
41
+ return makeAction({ tool: opts.tool, params: { ...extraParams, command: actionArg }, agentId: opts.agent, context });
42
+ }
43
+ export async function runCli(argv) {
44
+ const program = new Command();
45
+ let exitCode = 0;
46
+ program
47
+ .name("actionwall")
48
+ .description("Security firewall for AI agents — every tool call, command and request is checked against policy before it runs.")
49
+ .version(VERSION);
50
+ program
51
+ .command("check")
52
+ .description("Check an action against the policy (a shell command, or a JSON action)")
53
+ .argument("<action>", 'shell command, e.g. "rm -rf /tmp/*", or full JSON action {"tool":...,"params":{...}}')
54
+ .option("-t, --tool <name>", "tool name when passing a plain command", "shell")
55
+ .option("-p, --params <json>", "additional params as JSON")
56
+ .option("-c, --context <json>", 'context JSON, e.g. {"toolOutput":"…"} to test prompt-injection detection')
57
+ .option("-a, --agent <id>", "agent id", "cli-agent")
58
+ .option("--policy <path>", "policy file (default: ./actionwall.yaml, ./policies/default.yaml, or built-in)")
59
+ .option("--json", "emit the full Decision as JSON")
60
+ .option("--no-log", "do not append this decision to the audit log")
61
+ .action(async (actionArg, opts) => {
62
+ const policy = loadPolicy(resolvePolicyPath(opts.policy));
63
+ const engine = new ShieldEngine(policy, opts.log === false ? { audit: false } : {});
64
+ const action = buildAction(actionArg, opts);
65
+ const decision = engine.check(action);
66
+ if (opts.json) {
67
+ console.log(JSON.stringify(decision, null, 2));
68
+ }
69
+ else {
70
+ for (const line of formatDecision(decision, policy.audit.enabled && opts.log !== false ? policy.audit.log_dir : undefined)) {
71
+ console.log(line);
72
+ }
73
+ }
74
+ exitCode = decision.verdict === "ALLOW" ? 0 : decision.verdict === "ASK_HUMAN" ? 3 : 1;
75
+ });
76
+ program
77
+ .command("validate")
78
+ .description("Validate a policy file")
79
+ .option("--policy <path>", "policy file to validate (default resolution applies)")
80
+ .action((opts) => {
81
+ try {
82
+ const resolved = resolvePolicyPath(opts.policy);
83
+ const policy = loadPolicy(resolved);
84
+ const source = resolved ?? "built-in defaults";
85
+ console.log(green(`✓ Policy "${policy.name}" (${source}) is valid.`));
86
+ console.log(dim(` protected_paths: ${policy.file_policy.protected_paths.length} · max_bulk_delete: ${policy.file_policy.max_bulk_delete} · ` +
87
+ `tools: ${policy.tools.default} · fail_closed: ${policy.fail_closed}`));
88
+ }
89
+ catch (err) {
90
+ console.error(red(`✗ ${err.message}`));
91
+ exitCode = 2;
92
+ }
93
+ });
94
+ program
95
+ .command("log")
96
+ .description("Show the tamper-evident audit log")
97
+ .option("-n, --last <n>", "how many recent entries to show", "10")
98
+ .option("--verify", "verify the SHA-256 hash chain instead of listing")
99
+ .option("--dir <dir>", "audit log directory (default from policy)")
100
+ .option("--policy <path>", "policy file for log_dir resolution")
101
+ .option("--json", "emit entries as JSON")
102
+ .action((opts) => {
103
+ let logDir = opts.dir;
104
+ if (!logDir) {
105
+ const policy = loadPolicy(resolvePolicyPath(opts.policy));
106
+ logDir = policy.audit.log_dir;
107
+ }
108
+ const audit = new AuditLogger({ logDir, redactSecrets: false });
109
+ const file = audit.fileFor();
110
+ if (opts.verify) {
111
+ const v = audit.verify(file);
112
+ if (v.ok) {
113
+ console.log(green(`✓ Chain intact — ${v.entries} entries verified in ${file}`));
114
+ }
115
+ else {
116
+ console.error(red(`✗ CHAIN BROKEN in ${file} at entry #${v.brokenAt}: ${v.reason}`));
117
+ exitCode = 1;
118
+ }
119
+ return;
120
+ }
121
+ const entries = audit.tail(Number.parseInt(opts.last, 10) || 10, file);
122
+ if (entries.length === 0) {
123
+ console.log(dim(`No audit entries yet in ${file}. Run some agent actions first.`));
124
+ return;
125
+ }
126
+ for (const entry of entries) {
127
+ for (const line of formatAuditEntry(entry))
128
+ console.log(line);
129
+ }
130
+ });
131
+ program
132
+ .command("demo")
133
+ .description("Run the scripted demo agent (9 actions, 3 allowed, 5 blocked, 1 escalated) behind the firewall")
134
+ .option("--policy <path>", "policy file to run the demo with")
135
+ .option("--keep-sandbox", "keep the .actionwall-demo/ sandbox after the run")
136
+ .action(async (opts) => {
137
+ console.log(bold("ActionWall demo — a mock coding agent behind the firewall"));
138
+ console.log(dim("Every step is checked by the real engine with the real policy.\n"));
139
+ const result = await runDemo({ policyPath: opts.policy, keepSandbox: opts.keepSandbox, print: (l) => console.log(l) });
140
+ exitCode = result.blocked > 0 ? 1 : 0;
141
+ });
142
+ await program.parseAsync(argv, { from: "user" });
143
+ return exitCode;
144
+ }
145
+ const isMainInvocation = process.argv[1] ? import.meta.url === pathToFileURL(process.argv[1]).href : false;
146
+ if (isMainInvocation) {
147
+ runCli(process.argv.slice(2))
148
+ .then((code) => {
149
+ process.exitCode = code;
150
+ })
151
+ .catch((err) => {
152
+ console.error(red(`Error: ${err instanceof Error ? err.message : String(err)}`));
153
+ process.exitCode = 2;
154
+ });
155
+ }
156
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,61 @@
1
+ /**
2
+ * Append-only JSONL audit log with a SHA-256 hash chain.
3
+ *
4
+ * Every record embeds the hash of the previous record, so deleting or editing
5
+ * an entry after the fact breaks the chain and is caught by `verify()`.
6
+ * This gives agents (and their humans) a tamper-evident record of everything
7
+ * the firewall allowed or blocked.
8
+ *
9
+ * Records are written synchronously with appendFileSync. At firewall
10
+ * latencies (<50ms per decision) the syscall cost is acceptable and durability
11
+ * is worth more than throughput; batching is a listed roadmap item.
12
+ */
13
+ import type { Action, Decision } from "./types.js";
14
+ export declare const GENESIS_HASH: string;
15
+ export interface AuditEntry {
16
+ seq: number;
17
+ timestamp: string;
18
+ prevHash: string;
19
+ hash: string;
20
+ decision: {
21
+ verdict: Decision["verdict"];
22
+ risk: Decision["risk"];
23
+ summary: string;
24
+ findings: Decision["findings"];
25
+ latencyMs: number;
26
+ };
27
+ action: {
28
+ id: string;
29
+ agentId: string;
30
+ tool: string;
31
+ params: string;
32
+ };
33
+ }
34
+ export interface ChainVerification {
35
+ file: string;
36
+ entries: number;
37
+ ok: boolean;
38
+ /** Sequence number of the first broken link, when ok is false. */
39
+ brokenAt?: number;
40
+ reason?: string;
41
+ }
42
+ export declare class AuditLogger {
43
+ private readonly logDir;
44
+ private readonly redactSecrets;
45
+ /** Cache of {file → {prevHash, seq}} so appends don't re-read the file. */
46
+ private readonly tips;
47
+ constructor(opts: {
48
+ logDir: string;
49
+ redactSecrets: boolean;
50
+ });
51
+ /** Today's log file: audit-YYYY-MM-DD.jsonl */
52
+ fileFor(date?: Date): string;
53
+ listFiles(): string[];
54
+ /** Append a decision (with its action) to today's log. Returns the entry written. */
55
+ append(decision: Decision, action: Action): AuditEntry;
56
+ /** Re-walk the whole chain of a log file and confirm every link. */
57
+ verify(file?: string): ChainVerification;
58
+ /** Last `n` entries of a log file (default today's), oldest last. */
59
+ tail(n: number, file?: string): AuditEntry[];
60
+ private tipFor;
61
+ }