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
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* HTTP service mode: run ActionWall as a policy-check service.
|
|
3
|
+
*
|
|
4
|
+
* GET /healthz → liveness + version
|
|
5
|
+
* POST /v1/check → body: Action JSON → 200 { decision }
|
|
6
|
+
*
|
|
7
|
+
* Per-tenant policies: send `x-actionwall-tenant: <id>`; each tenant id maps
|
|
8
|
+
* to its own loaded policy and engine. No header = the default policy.
|
|
9
|
+
* Unknown tenant → 400. Malformed body → 400. Oversized body → 413.
|
|
10
|
+
*
|
|
11
|
+
* The server is a thin transport wrapper around the same ShieldEngine the CLI
|
|
12
|
+
* uses: no extra dependencies (node:http), the engine never executes actions,
|
|
13
|
+
* and a crash inside handling degrades to a 500 without leaking stack traces.
|
|
14
|
+
*/
|
|
15
|
+
import { readFileSync } from "node:fs";
|
|
16
|
+
import { createServer } from "node:http";
|
|
17
|
+
import { createRequire } from "node:module";
|
|
18
|
+
import { parse as parseYaml } from "yaml";
|
|
19
|
+
import { ShieldEngine } from "../core/engine.js";
|
|
20
|
+
import { loadPolicy } from "../core/policy.js";
|
|
21
|
+
const require = createRequire(import.meta.url);
|
|
22
|
+
const { version: PACKAGE_VERSION } = require("../../package.json");
|
|
23
|
+
const MAX_BODY_BYTES = 1_000_000;
|
|
24
|
+
function readBody(req) {
|
|
25
|
+
return new Promise((resolve, reject) => {
|
|
26
|
+
let size = 0;
|
|
27
|
+
const chunks = [];
|
|
28
|
+
req.on("data", (chunk) => {
|
|
29
|
+
size += chunk.length;
|
|
30
|
+
if (size > MAX_BODY_BYTES) {
|
|
31
|
+
reject(Object.assign(new Error("request body too large"), { code: "TOO_LARGE" }));
|
|
32
|
+
req.destroy();
|
|
33
|
+
return;
|
|
34
|
+
}
|
|
35
|
+
chunks.push(chunk);
|
|
36
|
+
});
|
|
37
|
+
req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
|
|
38
|
+
req.on("error", reject);
|
|
39
|
+
});
|
|
40
|
+
}
|
|
41
|
+
function sendJson(res, status, body, extraHeaders = {}) {
|
|
42
|
+
res.writeHead(status, { "content-type": "application/json; charset=utf-8", ...extraHeaders });
|
|
43
|
+
res.end(JSON.stringify(body));
|
|
44
|
+
}
|
|
45
|
+
function isValidAction(value) {
|
|
46
|
+
if (typeof value !== "object" || value === null)
|
|
47
|
+
return false;
|
|
48
|
+
const v = value;
|
|
49
|
+
return typeof v.tool === "string" && v.tool.length > 0 && typeof v.params === "object" && v.params !== null;
|
|
50
|
+
}
|
|
51
|
+
async function handle(engines, defaultEngine, req, res) {
|
|
52
|
+
const url = (req.url ?? "/").split("?")[0];
|
|
53
|
+
if (req.method === "GET" && url === "/healthz") {
|
|
54
|
+
sendJson(res, 200, { ok: true, name: "actionwall", version: PACKAGE_VERSION });
|
|
55
|
+
return;
|
|
56
|
+
}
|
|
57
|
+
if (req.method !== "POST" || url !== "/v1/check") {
|
|
58
|
+
if (url === "/v1/check") {
|
|
59
|
+
sendJson(res, 405, { error: "method not allowed; use POST" });
|
|
60
|
+
return;
|
|
61
|
+
}
|
|
62
|
+
sendJson(res, 404, { error: "not found; see POST /v1/check and GET /healthz" });
|
|
63
|
+
return;
|
|
64
|
+
}
|
|
65
|
+
let engine = defaultEngine;
|
|
66
|
+
const tenant = req.headers["x-actionwall-tenant"];
|
|
67
|
+
if (tenant !== undefined) {
|
|
68
|
+
const id = Array.isArray(tenant) ? tenant[0] : tenant;
|
|
69
|
+
const tenantEngine = engines.get(id);
|
|
70
|
+
if (!tenantEngine) {
|
|
71
|
+
sendJson(res, 400, { error: `unknown tenant "${id}"` });
|
|
72
|
+
return;
|
|
73
|
+
}
|
|
74
|
+
engine = tenantEngine;
|
|
75
|
+
}
|
|
76
|
+
let raw;
|
|
77
|
+
try {
|
|
78
|
+
raw = await readBody(req);
|
|
79
|
+
}
|
|
80
|
+
catch (err) {
|
|
81
|
+
sendJson(res, 413, { error: err.code === "TOO_LARGE" ? "request body too large" : "failed to read request body" });
|
|
82
|
+
return;
|
|
83
|
+
}
|
|
84
|
+
let action;
|
|
85
|
+
try {
|
|
86
|
+
action = JSON.parse(raw || "{}");
|
|
87
|
+
}
|
|
88
|
+
catch {
|
|
89
|
+
sendJson(res, 400, { error: "request body is not valid JSON" });
|
|
90
|
+
return;
|
|
91
|
+
}
|
|
92
|
+
if (!isValidAction(action)) {
|
|
93
|
+
sendJson(res, 400, { error: "body must be an Action: { tool: string, params: object, agentId?, context? }" });
|
|
94
|
+
return;
|
|
95
|
+
}
|
|
96
|
+
const decision = engine.check(action);
|
|
97
|
+
sendJson(res, 200, { decision }, {
|
|
98
|
+
"x-actionwall-verdict": decision.verdict,
|
|
99
|
+
"x-actionwall-risk": decision.risk,
|
|
100
|
+
});
|
|
101
|
+
}
|
|
102
|
+
/**
|
|
103
|
+
* Load a tenants file: a YAML document mapping tenant ids to policy file
|
|
104
|
+
* paths, with an optional `default` entry used when no tenant header is sent.
|
|
105
|
+
*
|
|
106
|
+
* default: policies/default.yaml
|
|
107
|
+
* tenants:
|
|
108
|
+
* ci-bot: policies/strict.yaml
|
|
109
|
+
* analyst: policies/readonly.yaml
|
|
110
|
+
*/
|
|
111
|
+
export function loadTenantsFile(path) {
|
|
112
|
+
const data = parseYaml(readFileSync(path, "utf8"));
|
|
113
|
+
const tenants = {};
|
|
114
|
+
for (const [id, file] of Object.entries(data.tenants ?? {})) {
|
|
115
|
+
tenants[id] = loadPolicy(file);
|
|
116
|
+
}
|
|
117
|
+
return { tenants, defaultPolicyPath: data.default };
|
|
118
|
+
}
|
|
119
|
+
/** Create the HTTP server. Call `server.listen(port, host)` to start it. */
|
|
120
|
+
export function createActionWallServer(options) {
|
|
121
|
+
const engineOptions = options.audit === false ? { audit: false } : {};
|
|
122
|
+
const defaultEngine = new ShieldEngine(options.policy, engineOptions);
|
|
123
|
+
const engines = new Map();
|
|
124
|
+
if (options.tenants) {
|
|
125
|
+
for (const [id, policy] of Object.entries(options.tenants)) {
|
|
126
|
+
engines.set(id, new ShieldEngine(policy, engineOptions));
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
return createServer((req, res) => {
|
|
130
|
+
void handle(engines, defaultEngine, req, res).catch(() => {
|
|
131
|
+
if (!res.headersSent) {
|
|
132
|
+
sendJson(res, 500, { error: "internal error while evaluating the action" });
|
|
133
|
+
}
|
|
134
|
+
else {
|
|
135
|
+
res.end();
|
|
136
|
+
}
|
|
137
|
+
});
|
|
138
|
+
});
|
|
139
|
+
}
|
|
140
|
+
//# sourceMappingURL=serve.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"serve.js","sourceRoot":"","sources":["../../src/server/serve.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Homoglyph and mixed-script detection.
|
|
3
|
+
*
|
|
4
|
+
* Attackers swap Latin characters with lookalikes from other scripts
|
|
5
|
+
* (Cyrillic "а" U+0430, Greek "ο" U+03BF, and friends) so that malicious
|
|
6
|
+
* text looks harmless to a reviewer while reading differently to the model.
|
|
7
|
+
*
|
|
8
|
+
* Detection rule: a word that MIXES ordinary Latin letters with known
|
|
9
|
+
* confusable lookalikes is flagged. Pure non-Latin text (someone writing
|
|
10
|
+
* Russian or Greek on purpose) never triggers, which keeps the false-positive
|
|
11
|
+
* rate near zero for international users.
|
|
12
|
+
*/
|
|
13
|
+
export interface ConfusableHit {
|
|
14
|
+
/** The lookalike character itself. */
|
|
15
|
+
char: string;
|
|
16
|
+
/** The Latin letter it impersonates. */
|
|
17
|
+
latin: string;
|
|
18
|
+
/** Position in the inspected text. */
|
|
19
|
+
index: number;
|
|
20
|
+
}
|
|
21
|
+
export interface ConfusableScan {
|
|
22
|
+
/** Lookalike characters found, in order. */
|
|
23
|
+
hits: ConfusableHit[];
|
|
24
|
+
/** True when at least one word mixes Latin letters with lookalikes,
|
|
25
|
+
* which is the actual evasion signal. */
|
|
26
|
+
mixedScriptWordFound: boolean;
|
|
27
|
+
/** First mixed word, for evidence. */
|
|
28
|
+
example?: string;
|
|
29
|
+
}
|
|
30
|
+
/** Scan text for homoglyph evasion. Only mixed-script words count. */
|
|
31
|
+
export declare function scanConfusables(text: string): ConfusableScan;
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Homoglyph and mixed-script detection.
|
|
3
|
+
*
|
|
4
|
+
* Attackers swap Latin characters with lookalikes from other scripts
|
|
5
|
+
* (Cyrillic "а" U+0430, Greek "ο" U+03BF, and friends) so that malicious
|
|
6
|
+
* text looks harmless to a reviewer while reading differently to the model.
|
|
7
|
+
*
|
|
8
|
+
* Detection rule: a word that MIXES ordinary Latin letters with known
|
|
9
|
+
* confusable lookalikes is flagged. Pure non-Latin text (someone writing
|
|
10
|
+
* Russian or Greek on purpose) never triggers, which keeps the false-positive
|
|
11
|
+
* rate near zero for international users.
|
|
12
|
+
*/
|
|
13
|
+
/** Common lookalikes that map onto Latin letters. Far from exhaustive:
|
|
14
|
+
* covers the characters seen in real evasion attempts (brand and command
|
|
15
|
+
* impersonation) without dragging in whole Unicode tables. */
|
|
16
|
+
const CONFUSABLES = {
|
|
17
|
+
// Cyrillic
|
|
18
|
+
"\u0430": "a", "\u0435": "e", "\u043e": "o", "\u0440": "p", "\u0441": "c",
|
|
19
|
+
"\u0443": "y", "\u0445": "x", "\u0432": "b", "\u043d": "h", "\u043a": "k",
|
|
20
|
+
"\u043c": "m", "\u0442": "t", "\u0438": "i", "\u0456": "i", "\u0455": "s",
|
|
21
|
+
// Greek
|
|
22
|
+
"\u03bf": "o", "\u03b1": "a", "\u03b5": "e", "\u03c1": "p", "\u03bd": "n",
|
|
23
|
+
"\u03ba": "k", "\u03c4": "t", "\u03c5": "u", "\u03b9": "i", "\u03c7": "x",
|
|
24
|
+
// Armenian and fullwidth lookalikes seen in the wild
|
|
25
|
+
"\u0561": "a", "\u0575": "y", "\u0585": "o", "\uFF41": "a", "\uFF4F": "o",
|
|
26
|
+
"\uFF50": "p", "\uFF52": "r", "\uFF43": "c", "\uFF53": "s",
|
|
27
|
+
};
|
|
28
|
+
/** Scan text for homoglyph evasion. Only mixed-script words count. */
|
|
29
|
+
export function scanConfusables(text) {
|
|
30
|
+
const hits = [];
|
|
31
|
+
for (let i = 0; i < text.length; i++) {
|
|
32
|
+
const mapped = CONFUSABLES[text[i]];
|
|
33
|
+
if (mapped)
|
|
34
|
+
hits.push({ char: text[i], latin: mapped, index: i });
|
|
35
|
+
}
|
|
36
|
+
let mixedScriptWordFound = false;
|
|
37
|
+
let example;
|
|
38
|
+
// Split into letter runs so we can inspect each word in isolation.
|
|
39
|
+
const words = text.match(/[\p{L}\p{N}]+/gu) ?? [];
|
|
40
|
+
for (const word of words) {
|
|
41
|
+
let latin = 0;
|
|
42
|
+
let lookalike = 0;
|
|
43
|
+
for (const ch of word) {
|
|
44
|
+
if (CONFUSABLES[ch])
|
|
45
|
+
lookalike++;
|
|
46
|
+
else if (/[a-zA-Z]/.test(ch))
|
|
47
|
+
latin++;
|
|
48
|
+
}
|
|
49
|
+
if (latin > 0 && lookalike > 0) {
|
|
50
|
+
mixedScriptWordFound = true;
|
|
51
|
+
example ??= word;
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
return { hits, mixedScriptWordFound, example };
|
|
55
|
+
}
|
|
56
|
+
//# sourceMappingURL=homoglyphs.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"homoglyphs.js","sourceRoot":"","sources":["../../src/util/homoglyphs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;8DAE8D;AAC9D,MAAM,WAAW,GAA2B;IAC1C,WAAW;IACX,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG;IACzE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG;IACzE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG;IACzE,QAAQ;IACR,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG;IACzE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG;IACzE,qDAAqD;IACrD,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG;IACzE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG;CAC3D,CAAC;AAqBF,sEAAsE;AACtE,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,MAAM,IAAI,GAAoB,EAAE,CAAC;IACjC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC,CAAE,CAAC,CAAC;QACrC,IAAI,MAAM;YAAE,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAE,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;IACrE,CAAC;IAED,IAAI,oBAAoB,GAAG,KAAK,CAAC;IACjC,IAAI,OAA2B,CAAC;IAChC,mEAAmE;IACnE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,CAAC;IAClD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,IAAI,SAAS,GAAG,CAAC,CAAC;QAClB,KAAK,MAAM,EAAE,IAAI,IAAI,EAAE,CAAC;YACtB,IAAI,WAAW,CAAC,EAAE,CAAC;gBAAE,SAAS,EAAE,CAAC;iBAC5B,IAAI,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;gBAAE,KAAK,EAAE,CAAC;QACxC,CAAC;QACD,IAAI,KAAK,GAAG,CAAC,IAAI,SAAS,GAAG,CAAC,EAAE,CAAC;YAC/B,oBAAoB,GAAG,IAAI,CAAC;YAC5B,OAAO,KAAK,IAAI,CAAC;QACnB,CAAC;IACH,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,oBAAoB,EAAE,OAAO,EAAE,CAAC;AACjD,CAAC"}
|
package/dist/util/paths.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/util/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,wEAAwE;AACxE,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAC;AACrC,MAAM,CAAC,MAAM,cAAc,GAAG,EAAE,CAAC;AAEjC,MAAM,UAAU,UAAU,CAAC,CAAS;IAClC,IAAI,CAAC,KAAK,GAAG;QAAE,OAAO,OAAO,EAAE,CAAC;IAChC,IAAI,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9C,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,aAAa,CAAC,CAAS,EAAE,
|
|
1
|
+
{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/util/paths.ts"],"names":[],"mappings":"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"}
|
package/docs/ARCHITECTURE.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# ActionWall
|
|
1
|
+
# ActionWall: Architecture
|
|
2
2
|
|
|
3
3
|
## 1. Bird's-eye view
|
|
4
4
|
|
|
@@ -22,20 +22,20 @@ ActionWall is a **library first**. The engine is a pure(ish) function: `(Action,
|
|
|
22
22
|
|
|
23
23
|
## 2. Data model (src/core/types.ts)
|
|
24
24
|
|
|
25
|
-
- **Action
|
|
25
|
+
- **Action**: what the agent wants: `{ id, timestamp, agentId, tool, params, context }`.
|
|
26
26
|
`tool` is a canonical name (`shell`, `file.read`, `http.request`, …). `context.toolOutput` carries untrusted external content for injection scanning.
|
|
27
|
-
- **Finding
|
|
28
|
-
- **Decision
|
|
29
|
-
- **Verdict mapping
|
|
27
|
+
- **Finding**: one violation: `{ scanner, ruleId, severity, title, reason, policyRef, evidence }`. Evidence is always redacted and truncated.
|
|
28
|
+
- **Decision**: `{ verdict, risk, findings, summary, latencyMs, timestamp }`.
|
|
29
|
+
- **Verdict mapping**: policy `risk_thresholds`: severities in `block` → BLOCK, in `ask` → ASK_HUMAN, otherwise ALLOW.
|
|
30
30
|
|
|
31
31
|
## 3. The pipeline (src/core/engine.ts)
|
|
32
32
|
|
|
33
|
-
1. Run every scanner in order: toolPermissions → commandRisk → filePolicy → secrets → urlPolicy → injection. (Permissions first
|
|
33
|
+
1. Run every scanner in order: toolPermissions → commandRisk → filePolicy → secrets → urlPolicy → injection. (Permissions first, the cheap coarse gate; content scanners next.)
|
|
34
34
|
2. Aggregate: decision risk = max finding severity (LOW if none).
|
|
35
35
|
3. Map through `risk_thresholds`.
|
|
36
36
|
4. Append to the audit log (unless disabled or ALLOW with `log_allowed: false`).
|
|
37
37
|
|
|
38
|
-
**Failure semantics.** A scanner that throws produces a synthetic finding `SCANNER-FAILURE
|
|
38
|
+
**Failure semantics.** A scanner that throws produces a synthetic finding `SCANNER-FAILURE`, CRITICAL (block) when `fail_closed: true` (default), LOW when fail-open. An audit write failure does not lose the decision; it appends an `AUDIT-WRITE-FAILURE` finding. Rationale: a firewall that crashes open is worse than no firewall, but operators must be able to opt out explicitly for availability-critical paths.
|
|
39
39
|
|
|
40
40
|
## 4. Scanner contract
|
|
41
41
|
|
|
@@ -47,10 +47,10 @@ interface Scanner {
|
|
|
47
47
|
```
|
|
48
48
|
|
|
49
49
|
Rules for implementations:
|
|
50
|
-
- **Pure
|
|
50
|
+
- **Pure**: no command execution, no network. Read-only filesystem access is allowed where the scanner's purpose demands it (bulk-delete counting) and must be bounded.
|
|
51
51
|
- **Return []** for anything not applicable (e.g. commandRisk on an http.request).
|
|
52
|
-
- **Redact evidence
|
|
53
|
-
- **Cite policy
|
|
52
|
+
- **Redact evidence**: anything resembling a credential passes through `redactText()`.
|
|
53
|
+
- **Cite policy**: findings set `policyRef` so the report can point at the exact knob.
|
|
54
54
|
|
|
55
55
|
### Adding a scanner
|
|
56
56
|
|
|
@@ -58,32 +58,32 @@ Rules for implementations:
|
|
|
58
58
|
2. Add it to `DEFAULT_SCANNERS` in `src/core/engine.ts` (or inject via `new ShieldEngine(policy, { scanners })`).
|
|
59
59
|
3. Add tests + a row in REQUIREMENTS/README.
|
|
60
60
|
|
|
61
|
-
This is also the extension seam for ML-based classifiers (e.g. a small model scoring injection likelihood)
|
|
61
|
+
This is also the extension seam for ML-based classifiers (e.g. a small model scoring injection likelihood); they return findings like any rule-based scanner.
|
|
62
62
|
|
|
63
63
|
## 5. Key design decisions
|
|
64
64
|
|
|
65
|
-
### D1
|
|
65
|
+
### D1: Rule-based first, ML later
|
|
66
66
|
Rules are deterministic, testable, fast (~1–5 ms), auditable, and explainable. For a *firewall* (a control-plane component), "why was this blocked?" must have an exact answer. ML classifiers are a great **addition** (pluggable scanner) but a poor foundation: non-deterministic, unexplainable, and gameable.
|
|
67
67
|
|
|
68
|
-
### D2
|
|
69
|
-
The shell tokenizer (`util/shell.ts`) is quote-aware and handles chains (`&&`, `;`, `||`, `|`) so each segment is inspected; a fork bomb is matched on the full command because it spans operators. We deliberately do not resolve commands "the way bash would" beyond tokenization
|
|
68
|
+
### D2: Analyze, never execute
|
|
69
|
+
The shell tokenizer (`util/shell.ts`) is quote-aware and handles chains (`&&`, `;`, `||`, `|`) so each segment is inspected; a fork bomb is matched on the full command because it spans operators. We deliberately do not resolve commands "the way bash would" beyond tokenization: deeper emulation adds complexity and new bypasses; the residual ambiguity is handled by conservative rules (e.g. command substitution = MEDIUM, eval = HIGH).
|
|
70
70
|
|
|
71
|
-
### D3
|
|
71
|
+
### D3: Count, don't guess, for bulk deletes
|
|
72
72
|
The headline policy ("no more than 10 automatic deletions") is enforced by **actually counting** the files a glob would remove via a bounded, read-only walk (`util/paths.ts`: 5000-entry cap, depth 12, glob expansion). Severity escalates to CRITICAL when the count exceeds the limit. This turns an intention-based rule ("destructive") into a measurable one ("12 > 10").
|
|
73
73
|
|
|
74
|
-
### D4
|
|
75
|
-
All paths are home-expanded, resolved, and normalized to POSIX form with any Windows drive prefix stripped before matching (`/etc/**` and `~/.ssh/**` work everywhere). Because matching happens on the *resolved* path, `../../` traversal is defeated by construction
|
|
74
|
+
### D4: Path normalization against traversal & platform drift
|
|
75
|
+
All paths are home-expanded, resolved, and normalized to POSIX form with any Windows drive prefix stripped before matching (`/etc/**` and `~/.ssh/**` work everywhere). Because matching happens on the *resolved* path, `../../` traversal is defeated by construction: the resolved location is what gets policy-checked. Protected-path rules are first-match-wins so ordering is explicit in the policy file.
|
|
76
76
|
|
|
77
|
-
### D5
|
|
78
|
-
Well-known formats (AWS, GitHub, OpenAI, Stripe, Slack, JWT, PEM blocks) are regex signatures; unknown formats are covered by a Shannon-entropy heuristic (≥ 32 chars, entropy ≥ 4.0 → MEDIUM). Placeholder values (`changeme`, `${DB_PASS}`) are filtered to avoid alert fatigue. Critically, the same pattern set drives **log redaction
|
|
77
|
+
### D5: Secrets with signatures, entropy and redaction everywhere
|
|
78
|
+
Well-known formats (AWS, GitHub, OpenAI, Stripe, Slack, JWT, PEM blocks) are regex signatures; unknown formats are covered by a Shannon-entropy heuristic (≥ 32 chars, entropy ≥ 4.0 → MEDIUM). Placeholder values (`changeme`, `${DB_PASS}`) are filtered to avoid alert fatigue. Critically, the same pattern set drives **log redaction**: the audit trail can't store what the scanner would have blocked.
|
|
79
79
|
|
|
80
|
-
### D6
|
|
80
|
+
### D6: SSRF guard with a metadata-endpoint special case
|
|
81
81
|
`169.254.169.254` (and GCP/Aliyun equivalents) get CRITICAL because that's the canonical cloud-credential-theft path for compromised agents; the rest of RFC1918/loopback/link-local gets HIGH. Domain allow/deny lists support `*.example.com` wildcards; an empty allowlist means "any public domain".
|
|
82
82
|
|
|
83
|
-
### D7
|
|
84
|
-
JSONL records hash-chain to their predecessor (`hash = sha256(prevHash + record)`); `log --verify` re-walks the chain and names the first broken entry. A local attacker with filesystem write access can still rewrite the *whole* file consistently (they'd need to recompute every hash
|
|
83
|
+
### D7: Tamper-evident audit, not tamper-proof
|
|
84
|
+
JSONL records hash-chain to their predecessor (`hash = sha256(prevHash + record)`); `log --verify` re-walks the chain and names the first broken entry. A local attacker with filesystem write access can still rewrite the *whole* file consistently (they'd need to recompute every hash, which is feasible), so this is **tamper-evident**, not tamper-proof. Full integrity would need an external anchor (append-only remote sink, signing key in an HSM). See ROADMAP.
|
|
85
85
|
|
|
86
|
-
### D8
|
|
86
|
+
### D8: Fail-closed defaults, explicit escapes
|
|
87
87
|
Deny wins over allow in tool permissions; deny-by-default is one flag away; scanner crashes block. Everything that opens the firewall (`fail_open`, `allow_outside_workspace`, `log_allowed: false`) is an explicit, greppable policy decision.
|
|
88
88
|
|
|
89
89
|
## 6. Latency budget
|
package/docs/COMPARISON.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
# ActionWall
|
|
1
|
+
# ActionWall: Competitive Landscape
|
|
2
2
|
|
|
3
|
-
> Research snapshot: October 2026. Refresh before launch
|
|
3
|
+
> Research snapshot: October 2026. Refresh before launch: this space moves fast (see the [GitHub `ai-firewall` topic](https://github.com/topics/ai-firewall) for new entrants). Links go to primary sources where possible.
|
|
4
4
|
|
|
5
5
|
**Purpose:** establish that ActionWall's niche is deliberate, not accidental. The one-line summary:
|
|
6
6
|
|
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
│ OS sandbox / container (E2B, Firecracker, Docker) │ hard isolation,
|
|
14
14
|
│ │ coarse grain
|
|
15
15
|
├──────────────────────────────────────────────────────────────┤
|
|
16
|
-
│ ★ ACTION POLICY LAYER
|
|
16
|
+
│ ★ ACTION POLICY LAYER · ActionWall lives here │ deterministic,
|
|
17
17
|
│ (tool calls, commands, file ops, URLs, secrets) │ per-action,
|
|
18
18
|
│ │ explainable
|
|
19
19
|
├──────────────────────────────────────────────────────────────┤
|
|
@@ -24,22 +24,22 @@
|
|
|
24
24
|
└──────────────────────────────────────────────────────────────┘
|
|
25
25
|
```
|
|
26
26
|
|
|
27
|
-
Most public effort has gone into the *bottom* layers (scanning text) and the *top* layer (sandboxing). The middle layer
|
|
27
|
+
Most public effort has gone into the *bottom* layers (scanning text) and the *top* layer (sandboxing). The middle layer, deterministic per-action policy, is where ActionWall plays, and it composes with the others rather than replacing them.
|
|
28
28
|
|
|
29
29
|
## Comparison table
|
|
30
30
|
|
|
31
31
|
| Project | Shape | What it inspects | Strength | Gap ActionWall fills |
|
|
32
32
|
|---|---|---|---|---|
|
|
33
33
|
| **Meta Llama Guard / Prompt Guard 2** | model-based classifier | prompts & responses (text) | industry-standard content classification; fast small models | probabilistic, not explainable; benchmarked weak on *indirect* injection ([promptfoo's finding](https://www.promptfoo.dev/lm-security-db/vuln/llm-guardrail-benchmark-lies-10b59e81/)); no tool-action policy, no audit trail, requires model hosting |
|
|
34
|
-
| **Rebuff** | detection framework | prompt text (heuristics + LLM + canary tokens + vector DB) | layered injection detection, canary-token exfil proofing | Python, LLM-dependent; text-level only
|
|
34
|
+
| **Rebuff** | detection framework | prompt text (heuristics + LLM + canary tokens + vector DB) | layered injection detection, canary-token exfil proofing | Python, LLM-dependent; text-level only: says nothing about what the agent *does* next |
|
|
35
35
|
| **NVIDIA NeMo Guardrails** | guardrail orchestration (Colang) | conversation flows; can wrap other detectors | mature, flexible rails, big ecosystem | dialog-centric; Python; policies are conversational, not per-tool-action with policy files + exit codes |
|
|
36
36
|
| **Meta LlamaFirewall** | agent security framework | multi-step agent workflows, content | major-vendor backing, broad scope | Python-first; heavier footprint; not an embeddable TS library with a CLI/audit-verify story |
|
|
37
37
|
| **Agent-Wall** (MCP) | MCP client↔server proxy | tool calls passing through MCP | drop-in protection for MCP agents without code changes | deployment = infrastructure proxy, MCP-transport-scoped; ActionWall is an embeddable library + CLI across *all* tool shapes (shell, file.*, http.*) with filesystem-measured rules |
|
|
38
|
-
| **@goplus/agentguard** (npm, v1.2.1, active
|
|
39
|
-
| **agentgate** (npm, v0.16.0, ISC) | agent API gateway | reads execute immediately, **writes queue for human approval** | independently arrived at the ASK_HUMAN idea
|
|
38
|
+
| **@goplus/agentguard** (npm, v1.2.1, active, 27 releases) | TS guard library + Claude Code skills / MCP hooks | dangerous commands, data leaks, secrets; "20 detection rules, runtime action evaluation, trust registry" | closest npm overlap; actively maintained; backed by GoPlus (a web3 security company); MIT | web3/vendor-flavored (ships axios network calls, a trust registry, Claude-Code/MCP orientation); ActionWall's differentiation to defend: offline & dependency-light, framework-agnostic `(Action, Policy) → Decision` API, filesystem-measured bulk-delete, policy-as-code with zod + CI exit codes, hash-chained audit with `--verify` |
|
|
39
|
+
| **agentgate** (npm, v0.16.0, ISC) | agent API gateway | reads execute immediately, **writes queue for human approval** | independently arrived at the ASK_HUMAN idea: external validation that human-in-the-loop is the right primitive | gateway-shaped (transport level, its own client model), not an embeddable content-aware policy engine with shell/file/secret scanners |
|
|
40
40
|
| **agent-firewall** (npm) | agent↔LLM proxy | loop detection, prompt caching, budget caps | operational cost/behavior controls | different problem (cost & runaway loops), not security policy on tool actions |
|
|
41
|
-
| **promptfoo** | eval / red-team harness | your entire guardrail stack | perfect complement: adversarial testing of guardrails in CI | not a runtime control
|
|
42
|
-
| **E2B / container sandboxes** | execution isolation | everything inside the sandbox | hard guarantees, real isolation | coarse grain
|
|
41
|
+
| **promptfoo** | eval / red-team harness | your entire guardrail stack | perfect complement: adversarial testing of guardrails in CI | not a runtime control; pair it: promptfoo tests ActionWall's policies |
|
|
42
|
+
| **E2B / container sandboxes** | execution isolation | everything inside the sandbox | hard guarantees, real isolation | coarse grain: no explainable per-action verdicts, no policy files, heavy ops; ActionWall complements (see THREAT_MODEL deployment stack) |
|
|
43
43
|
| **Framework-native approvals** (Claude Code permission prompts, etc.) | UX-level prompts | each tool call | zero setup, human in the loop | not policy-as-code, no programmatic audit export, per-app behavior; ActionWall makes the same idea deterministic, configurable, and logged |
|
|
44
44
|
|
|
45
45
|
## Positioning statement (for README/launch)
|
|
@@ -48,27 +48,27 @@ ActionWall is **not** another prompt-injection scanner and **not** a sandbox. It
|
|
|
48
48
|
|
|
49
49
|
## Key differentiators
|
|
50
50
|
|
|
51
|
-
1. **Action-level, deterministic, explainable
|
|
52
|
-
2. **Measured blast radius
|
|
53
|
-
3. **TypeScript-first
|
|
54
|
-
4. **Policy-as-code
|
|
55
|
-
5. **Tamper-evident audit
|
|
56
|
-
6. **Honest scope
|
|
51
|
+
1. **Action-level, deterministic, explainable**: every block cites a rule ID and the exact policy knob (`file_policy.max_bulk_delete`), unlike classifier verdicts.
|
|
52
|
+
2. **Measured blast radius**: `rm -rf <glob>` is evaluated by counting real files (bounded walk), turning "destructive" from an opinion into a number.
|
|
53
|
+
3. **TypeScript-first**: most guardrail frameworks are Python-first; the JS agent ecosystem (LangChain.js, Vercel AI SDK, TS MCP servers) is underserved.
|
|
54
|
+
4. **Policy-as-code**: YAML + zod validation + `actionwall validate` in CI + exit codes built for pipelines.
|
|
55
|
+
5. **Tamper-evident audit**: SHA-256 hash chain with `log --verify`, secrets redacted at write time.
|
|
56
|
+
6. **Honest scope**: documented limitations (THREAT_MODEL §6) instead of "prevents prompt injection" claims.
|
|
57
57
|
|
|
58
58
|
## Key sources
|
|
59
59
|
|
|
60
|
-
- [GitHub topic: ai-firewall](https://github.com/topics/ai-firewall)
|
|
61
|
-
- [promptfoo LLM Security DB: guardrail benchmark limitations](https://www.promptfoo.dev/lm-security-db/vuln/llm-guardrail-benchmark-lies-10b59e81/)
|
|
62
|
-
- [promptfoo: testing guardrails guide](https://www.promptfoo.dev/docs/guides/testing-guardrails/)
|
|
63
|
-
- [arXiv 2502.15427: benchmarking guardrails against prompt injection](https://arxiv.org/html/2502.15427v1)
|
|
64
|
-
- [Snyk: Nx malicious package weaponizing AI coding agents](https://snyk.io/blog/weaponizing-ai-coding-agents-for-malware-in-the-nx-malicious-package/)
|
|
65
|
-
- [GMI Cloud: guardrails in production](https://www.gmicloud.ai/en/blog/llm-guardrails-in-production-content-filtering-jailbreak-detection-and-why-guardrails-alone-are-not-enough)
|
|
60
|
+
- [GitHub topic: ai-firewall](https://github.com/topics/ai-firewall), a running index of AI security gateways (HTTP + MCP)
|
|
61
|
+
- [promptfoo LLM Security DB: guardrail benchmark limitations](https://www.promptfoo.dev/lm-security-db/vuln/llm-guardrail-benchmark-lies-10b59e81/), the indirect-injection failures in Llama Guard 3 / Prompt Guard 2
|
|
62
|
+
- [promptfoo: testing guardrails guide](https://www.promptfoo.dev/docs/guides/testing-guardrails/), the methodology for benchmarking guardrails (missed attacks vs false positives)
|
|
63
|
+
- [arXiv 2502.15427: benchmarking guardrails against prompt injection](https://arxiv.org/html/2502.15427v1), detection gains vs false-positive costs for NeMo-style rails
|
|
64
|
+
- [Snyk: Nx malicious package weaponizing AI coding agents](https://snyk.io/blog/weaponizing-ai-coding-agents-for-malware-in-the-nx-malicious-package/), the incident class that motivates action-level controls
|
|
65
|
+
- [GMI Cloud: guardrails in production](https://www.gmicloud.ai/en/blog/llm-guardrails-in-production-content-filtering-jailbreak-detection-and-why-guardrails-alone-are-not-enough), the production pattern of stacking a fast classifier under an orchestration layer
|
|
66
66
|
|
|
67
67
|
## Evaluating the landscape: key questions, answered (verified against the npm registry, October 2026)
|
|
68
68
|
|
|
69
69
|
Answers to the standard competitor-evaluation questions, with the evidence basis noted. Claims about other packages come from their npm metadata and published descriptions, not source audits.
|
|
70
70
|
|
|
71
|
-
**What do they do?** The space splits into five shapes: *text classifiers* (Llama Guard, Prompt Guard 2
|
|
71
|
+
**What do they do?** The space splits into five shapes: *text classifiers* (Llama Guard, Prompt Guard 2: score the words going into and out of the model), *detection frameworks* (Rebuff: layered injection detection with canary tokens), *conversation frameworks* (NeMo Guardrails: Colang rules around dialog), *proxies/gateways* (agent-firewall for cost/loops, agentgate for write approvals, Agent-Wall for MCP transport), and *sandboxes* (E2B, containers: isolate execution). Adjacent-but-different: `agentshield` on npm is a hardlink *backup/rollback* tool (acts after the damage), and promptfoo is an eval harness, not a control.
|
|
72
72
|
|
|
73
73
|
**What don't they do?** No verified package combines: an in-process deterministic verdict on the individual tool action + a filesystem-*measured* blast radius (counting what a delete would remove) + policy-as-code validated at load + a hash-chained, verifiable audit log + a TypeScript-first API. Each tool covers one layer; the action-policy layer with measurement is the open niche.
|
|
74
74
|
|
|
@@ -82,18 +82,18 @@ Answers to the standard competitor-evaluation questions, with the evidence basis
|
|
|
82
82
|
|
|
83
83
|
**Do they protect shell commands?** @goplus/agentguard blocks "dangerous commands" (20 rules, per its description). ActionWall's depth: quote-aware tokenization, chain/pipeline-aware analysis, ~15 rule families (reverse shells, fork bombs, obfuscation, raw device writes…), each finding citing a rule ID and the exact policy knob.
|
|
84
84
|
|
|
85
|
-
**Do they address prompt injection?** The classifier tier is crowded (Llama Guard, Prompt Guard, Rebuff, Lakera…) and benchmarked weak on *indirect* injection. ActionWall doesn't compete there: it detects common textual patterns and
|
|
85
|
+
**Do they address prompt injection?** The classifier tier is crowded (Llama Guard, Prompt Guard, Rebuff, Lakera…) and benchmarked weak on *indirect* injection. ActionWall doesn't compete there: it detects common textual patterns and, the real defense, constrains what an injected agent can *do*. Even a perfect classifier can't stop a hallucinated `rm -rf`; someone must judge the action.
|
|
86
86
|
|
|
87
87
|
**Do they have good TypeScript support?** The systemic gap: the major frameworks are Python-first. The JS/TS agent ecosystem (LangChain.js, Vercel AI SDK, TS MCP servers) has essentially one TS-native option (@goplus/agentguard, web3-oriented). This is the clearest market gap ActionWall fills.
|
|
88
88
|
|
|
89
|
-
**Are their APIs cumbersome?** Classifier APIs are async, remote, and metered per call. ActionWall: `engine.check(action)
|
|
89
|
+
**Are their APIs cumbersome?** Classifier APIs are async, remote, and metered per call. ActionWall: `engine.check(action)`: synchronous, local, ~1–5 ms, zero network.
|
|
90
90
|
|
|
91
|
-
**Are they actively maintained?** @goplus/agentguard: yes (27 releases). agent-firewall: rapid successive releases (churn risk). The big frameworks: maintained by Meta/NVIDIA. Honest caveat that applies to ActionWall too: single-maintainer projects carry bus-factor risk
|
|
91
|
+
**Are they actively maintained?** @goplus/agentguard: yes (27 releases). agent-firewall: rapid successive releases (churn risk). The big frameworks: maintained by Meta/NVIDIA. Honest caveat that applies to ActionWall too: single-maintainer projects carry bus-factor risk, mitigated here by a tiny dependency surface and deep docs.
|
|
92
92
|
|
|
93
|
-
**Do they have good tests?** Directly verifiable only for ActionWall (76 tests covering every rule, tamper detection, CLI exit codes). For competitors, the check is CI badges and repo inspection
|
|
93
|
+
**Do they have good tests?** Directly verifiable only for ActionWall (76 tests covering every rule, tamper detection, CLI exit codes). For competitors, the check is CI badges and repo inspection, a question to ask *them*.
|
|
94
94
|
|
|
95
|
-
**Can ActionWall provide a simpler developer experience?** Yes
|
|
95
|
+
**Can ActionWall provide a simpler developer experience?** Yes, that is the pitch: deterministic defaults that work with zero config, a sync API, a 30-second `npx actionwall demo`, human-readable verdicts, and a verifiable audit trail. Simple to adopt, honest about limits, measurable when it blocks.
|
|
96
96
|
|
|
97
97
|
### Naming provenance (npm registry, verified 2026-10-01)
|
|
98
98
|
|
|
99
|
-
`agentshield
|
|
99
|
+
`agentshield`: taken (backup tool, tomsun28) · `agent-firewall`: taken (LLM proxy) · `agentward`: squatted by a placeholder package · `agentgate`: taken (write-approval gateway) · **`actionwall`: free, adopted** · free at time of check: `toolward`, `agentmoat`, `agentcage`.
|
package/docs/POLICY_REFERENCE.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
# ActionWall
|
|
1
|
+
# ActionWall: Policy Reference
|
|
2
2
|
|
|
3
|
-
Policies are YAML (or JSON) documents validated with zod at load time. **Every field is optional
|
|
3
|
+
Policies are YAML (or JSON) documents validated with zod at load time. **Every field is optional**: omitted sections fall back to the built-in defaults shown in `policies/default.yaml`. Invalid fields fail loudly (`actionwall validate`).
|
|
4
4
|
|
|
5
5
|
```bash
|
|
6
6
|
actionwall validate --policy policies/strict.yaml
|
|
@@ -12,7 +12,7 @@ actionwall validate --policy policies/strict.yaml
|
|
|
12
12
|
|---|---|---|---|
|
|
13
13
|
| `version` | `1` | `1` | Schema version. |
|
|
14
14
|
| `name` | string | `"default"` | Policy name, shown by `validate`. |
|
|
15
|
-
| `description` | string |
|
|
15
|
+
| `description` | string | - | Free text. |
|
|
16
16
|
| `fail_closed` | bool | `true` | Scanner crash ⇒ CRITICAL finding (block). Set `false` for fail-open. |
|
|
17
17
|
| `risk_thresholds.block` | RiskLevel[] | `[HIGH, CRITICAL]` | Severities that BLOCK. |
|
|
18
18
|
| `risk_thresholds.ask` | RiskLevel[] | `[MEDIUM]` | Severities that escalate to ASK_HUMAN. Anything else is ALLOW. |
|
|
@@ -26,7 +26,7 @@ actionwall validate --policy policies/strict.yaml
|
|
|
26
26
|
| `deny` | string[] | `[]` | Denied tools. **Deny always wins over allow.** |
|
|
27
27
|
| `agents` | map | `{}` | Per-agent override: `agents.<agentId>` may set `default`, `allow`, `deny`. When present, an agent's own lists replace the global ones. |
|
|
28
28
|
|
|
29
|
-
Example
|
|
29
|
+
Example: a junior agent that may only read and search:
|
|
30
30
|
|
|
31
31
|
```yaml
|
|
32
32
|
tools:
|
|
@@ -50,7 +50,7 @@ command_risk:
|
|
|
50
50
|
- "kubectl\\s+delete\\s+(?!pod)" # negative lookahead works too
|
|
51
51
|
```
|
|
52
52
|
|
|
53
|
-
Built-in command rules (not configurable individually
|
|
53
|
+
Built-in command rules (not configurable individually; remove the scanner if you need to): rootish `rm` targets, bulk deletes, recursive+force deletion, pipe-to-shell, process-substitution exec, privilege escalation (`sudo`/`su`/`doas`), fork bombs, `dd of=/dev/*`, `mkfs*`, power commands, reverse shells (`nc -e`, `/dev/tcp/`, `socat EXEC:`), env dumps, eval/base64-decode obfuscation, command substitution, `chmod 777`, `git push --force`, remote copies, secret-file reads, custom patterns, overlong commands.
|
|
54
54
|
|
|
55
55
|
## `file_policy`
|
|
56
56
|
|
|
@@ -62,11 +62,11 @@ Built-in command rules (not configurable individually — remove the scanner if
|
|
|
62
62
|
| `allow_outside_workspace` | bool | `false` | If false: writes/deletes outside the workspace ⇒ HIGH, reads ⇒ MEDIUM. |
|
|
63
63
|
|
|
64
64
|
**Path rule** = `{ path, permissions, description? }` where `permissions` is one of:
|
|
65
|
-
- `[deny]
|
|
66
|
-
- `[readonly]
|
|
67
|
-
- `[allow]
|
|
65
|
+
- `[deny]`: no access at all
|
|
66
|
+
- `[readonly]`: reads allowed, writes/deletes blocked
|
|
67
|
+
- `[allow]`: everything allowed (use to punch holes in earlier rules)
|
|
68
68
|
|
|
69
|
-
**Ordering matters
|
|
69
|
+
**Ordering matters**: first match wins:
|
|
70
70
|
|
|
71
71
|
```yaml
|
|
72
72
|
protected_paths:
|
|
@@ -112,6 +112,30 @@ Built-in signatures: AWS access/secret keys, GitHub tokens, OpenAI/Anthropic key
|
|
|
112
112
|
|
|
113
113
|
Scans `context.toolOutput` and `context.userPrompt`. Pattern families: instruction overrides, fake system markers, prompt-extraction requests, role overrides, urgent-execute directives, impersonated assistant turns, markdown-image exfiltration (⇒ HIGH immediately), hidden zero-width characters.
|
|
114
114
|
|
|
115
|
+
## `rules`
|
|
116
|
+
|
|
117
|
+
Tune individual scanner rules without touching scanner code. Both subsections are optional. Protected rules (`SCANNER-FAILURE`, `AUDIT-WRITE-FAILURE`) can never be tuned.
|
|
118
|
+
|
|
119
|
+
| Field | Type | Default | Meaning |
|
|
120
|
+
|---|---|---|---|
|
|
121
|
+
| `severities` | map of ruleId to RiskLevel | `{}` | Override the severity of any finding by rule ID. Downgrades soften the verdict, upgrades harden it. |
|
|
122
|
+
| `exceptions` | `{ruleId, matches, reason?}[]` | `[]` | Drop findings whose rule ID matches and whose evidence (the path or command text) matches the glob in `matches`. |
|
|
123
|
+
|
|
124
|
+
```yaml
|
|
125
|
+
rules:
|
|
126
|
+
severities:
|
|
127
|
+
CMD-WORLD-WRITABLE: MEDIUM # world-writable files are acceptable here
|
|
128
|
+
exceptions:
|
|
129
|
+
- ruleId: FP-PROTECTED-READ
|
|
130
|
+
matches: "**/*.pem"
|
|
131
|
+
reason: build agents may read certificates
|
|
132
|
+
- ruleId: CMD-PRIVILEGE-ESCALATION
|
|
133
|
+
matches: "sudo systemctl restart *"
|
|
134
|
+
reason: ops runbook restarts
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
Exceptions are evidence-scoped: `.env` stays denied even when `**/*.pem` is excepted. The scanner-failure and audit-failure paths are always immune, so tuning can never disable the firewall's own failure reporting.
|
|
138
|
+
|
|
115
139
|
## `audit`
|
|
116
140
|
|
|
117
141
|
| Field | Type | Default | Meaning |
|
|
@@ -123,4 +147,4 @@ Scans `context.toolOutput` and `context.userPrompt`. Pattern families: instructi
|
|
|
123
147
|
|
|
124
148
|
## Full example (strict production policy)
|
|
125
149
|
|
|
126
|
-
See [`policies/strict.yaml`](../policies/strict.yaml)
|
|
150
|
+
See [`policies/strict.yaml`](../policies/strict.yaml): deny-by-default tools, egress allowlist, `hits_for_high: 1`, and per-agent restrictions. [`policies/readonly.yaml`](../policies/readonly.yaml) shows the whole-filesystem `**` readonly pattern with deny rules ordered before it.
|