@mokuyoaxis/agent-guard 0.2.5-rc2 → 0.2.5
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/CONTRIBUTING.md +24 -0
- package/README.md +52 -18
- package/README.zh-CN.md +46 -15
- package/SECURITY.md +18 -10
- package/adapters/dsh/README.md +39 -6
- package/adapters/dsh/harness/README.md +5 -0
- package/adapters/dsh/harness/guard_lab.py +3 -2
- package/adapters/dsh/lib/index.js +127 -33
- package/adapters/kimi-code/harness/README.md +5 -0
- package/core/lab.py +5 -2
- package/core/messages.py +40 -0
- package/core/policy.py +2 -1
- package/docs/README.md +29 -8
- package/docs/design/architecture.md +9 -5
- package/docs/design/compatibility.md +43 -3
- package/docs/design/threat-model.md +2 -2
- package/docs/guides/getting-started.md +28 -12
- package/docs/guides/harness-capabilities.md +9 -2
- package/docs/guides/recovery-feedback.md +98 -0
- package/docs/history/friction.md +21 -1
- package/docs/lab/blue-team-calibration.md +45 -0
- package/docs/lab/examples/blue-team-calibration.py +53 -0
- package/docs/lab/guard-lab.md +12 -2
- package/docs/releases/release-notes-0.2.5-rc3.md +82 -0
- package/docs/releases/release-notes-0.2.5.md +123 -0
- package/docs/reports/blue-team-lab-2026-10.md +73 -0
- package/docs/research/README.md +41 -0
- package/docs/research/content-authorization.md +54 -0
- package/docs/research/dataflow-observability.md +48 -0
- package/docs/research/delegation-provenance.md +56 -0
- package/docs/research/evaluation-method.md +51 -0
- package/docs/research/lab-observations-2026-10.json +43 -0
- package/package.json +1 -1
- package/skills/delete-guard/SKILL.md +31 -14
- package/skills/delete-guard/references/policy.md +20 -6
- package/skills/delete-guard/scripts/check.py +13 -0
- package/skills/delete-guard/scripts/gc.py +4 -2
- package/skills/delete-guard/scripts/safe_delete.py +20 -14
- package/skills/delete-guard/scripts/status.py +9 -0
- package/skills/exfil-guard/references/rules.md +2 -2
|
@@ -27,8 +27,12 @@
|
|
|
27
27
|
|
|
28
28
|
import fs from "node:fs";
|
|
29
29
|
import path from "node:path";
|
|
30
|
+
import { execFile } from "node:child_process";
|
|
31
|
+
import { promisify } from "node:util";
|
|
30
32
|
import { fileURLToPath } from "node:url";
|
|
31
33
|
|
|
34
|
+
const runFile = promisify(execFile);
|
|
35
|
+
|
|
32
36
|
export const name = "agent_guard";
|
|
33
37
|
|
|
34
38
|
/** Services that must resolve before apply() runs. */
|
|
@@ -217,7 +221,13 @@ function dialectSelector(args, config, env) {
|
|
|
217
221
|
function buildRuntime(ctx, config, shell, systemPrompt) {
|
|
218
222
|
const repoRoot = config.repoRoot || PACKAGE_ROOT;
|
|
219
223
|
const scriptsDir = path.join(repoRoot, "skills", "delete-guard", "scripts");
|
|
220
|
-
const
|
|
224
|
+
const diagnostics = {
|
|
225
|
+
startup_check: "NOT_RUN",
|
|
226
|
+
startup_scope: "plugin_process",
|
|
227
|
+
hook_registered: false,
|
|
228
|
+
last_checker_result: "NOT_RUN",
|
|
229
|
+
host_interception: "UNVERIFIED",
|
|
230
|
+
};
|
|
221
231
|
|
|
222
232
|
// The caller's sandbox policy travels with the session so guard
|
|
223
233
|
// invocations inherit exactly what the calling agent already has.
|
|
@@ -277,7 +287,7 @@ function buildRuntime(ctx, config, shell, systemPrompt) {
|
|
|
277
287
|
systemPrompt,
|
|
278
288
|
repoRoot,
|
|
279
289
|
scriptsDir,
|
|
280
|
-
|
|
290
|
+
diagnostics,
|
|
281
291
|
shQuote,
|
|
282
292
|
runScript,
|
|
283
293
|
outText,
|
|
@@ -288,21 +298,37 @@ function buildRuntime(ctx, config, shell, systemPrompt) {
|
|
|
288
298
|
// Async functions cannot be mistaken for constructor plugins by Cordis.
|
|
289
299
|
// The host must await optional read-guard startup before admitting work.
|
|
290
300
|
export async function apply(ctx, config) {
|
|
301
|
+
function refuseStartup(detail) {
|
|
302
|
+
const code = config.readResultGuard ? "READ_GUARD_STARTUP_REFUSED" : "GUARD_STARTUP_FAILED";
|
|
303
|
+
throw new Error(`[agent-guard] ${code}: ${detail} No guard hook or tools were registered. Other host tools may still run.`);
|
|
304
|
+
}
|
|
291
305
|
const shell = ctx.get ? ctx.get("shell") : undefined;
|
|
292
306
|
if (shell === undefined) {
|
|
293
|
-
|
|
294
|
-
console.error("[agent-guard] shell service unavailable; adapter disabled");
|
|
295
|
-
return;
|
|
307
|
+
refuseStartup("The shell service is unavailable.");
|
|
296
308
|
}
|
|
297
309
|
const systemPrompt = ctx.get ? ctx.get("systemPrompt") : undefined;
|
|
298
310
|
const rt = buildRuntime(ctx, config, shell, systemPrompt);
|
|
299
311
|
|
|
300
|
-
if (!rt.
|
|
301
|
-
|
|
302
|
-
console.error("[agent-guard] check.py not found under", rt.repoRoot);
|
|
303
|
-
return;
|
|
312
|
+
if (!fs.existsSync(path.join(rt.scriptsDir, "check.py"))) {
|
|
313
|
+
refuseStartup("check.py was not found. Check the package or repoRoot setting.");
|
|
304
314
|
}
|
|
305
315
|
|
|
316
|
+
// --help loads Python and the checker imports without assessing a command
|
|
317
|
+
// or writing guard metadata. This checks the plugin process environment;
|
|
318
|
+
// the caller's shell/sandbox environment is only exercised by actual tools.
|
|
319
|
+
try {
|
|
320
|
+
await runFile("python3", [path.join(rt.scriptsDir, "check.py"), "--help"], {
|
|
321
|
+
timeout: 10000,
|
|
322
|
+
maxBuffer: 65536,
|
|
323
|
+
});
|
|
324
|
+
} catch (error) {
|
|
325
|
+
refuseStartup(error.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER" ?
|
|
326
|
+
"The local checker startup check exceeded its output limit. Check the package and checker entry point." :
|
|
327
|
+
error.killed ? "The local checker startup check timed out." :
|
|
328
|
+
"The local Python checker could not run. Check python3 on the plugin process PATH and the checker imports.");
|
|
329
|
+
}
|
|
330
|
+
rt.diagnostics.startup_check = "PASSED";
|
|
331
|
+
|
|
306
332
|
if (config.readResultGuard) {
|
|
307
333
|
return import("./read_result_guard.js").then(async ({ installReadResultGuard }) => {
|
|
308
334
|
await installReadResultGuard(ctx, config, rt.repoRoot);
|
|
@@ -319,6 +345,13 @@ function contribute(ctx, config, rt) {
|
|
|
319
345
|
ctx.effect(() => {
|
|
320
346
|
const disposers = [];
|
|
321
347
|
|
|
348
|
+
function checkerFailure(code, detail) {
|
|
349
|
+
rt.diagnostics.last_checker_result = code;
|
|
350
|
+
const reason = `[agent-guard] ${code}: ${detail} Command denied (fail-closed).`;
|
|
351
|
+
console.error(reason);
|
|
352
|
+
return { kind: "deny", reason };
|
|
353
|
+
}
|
|
354
|
+
|
|
322
355
|
// ---- 1) interception -------------------------------------------------
|
|
323
356
|
disposers.push(
|
|
324
357
|
ctx.on("tools/pre-execute", async (exec, next) => {
|
|
@@ -352,20 +385,23 @@ function contribute(ctx, config, rt) {
|
|
|
352
385
|
exec
|
|
353
386
|
);
|
|
354
387
|
} catch (_err) {
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
388
|
+
return checkerFailure("CHECKER_EXECUTION_FAILED",
|
|
389
|
+
"The checker could not start or finish. Check Python and the caller's shell environment; inspect recovery state before retrying.");
|
|
390
|
+
}
|
|
391
|
+
if (result.timedOut) {
|
|
392
|
+
return checkerFailure("CHECKER_TIMEOUT",
|
|
393
|
+
"The checker timed out. Inspect recovery state before retrying.");
|
|
394
|
+
}
|
|
395
|
+
if (![0, 2, 3].includes(result.exitCode)) {
|
|
396
|
+
return checkerFailure("CHECKER_PROCESS_FAILED",
|
|
397
|
+
"The checker did not complete with a supported exit status. Check the Python runtime and recovery state.");
|
|
360
398
|
}
|
|
361
399
|
const verdict = rt.parseJson(rt.outText(result.stdout));
|
|
362
|
-
if (!verdict || !verdict.decision) {
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
kind: "deny",
|
|
366
|
-
reason: "[agent-guard] unparseable guard output (fail-closed)",
|
|
367
|
-
};
|
|
400
|
+
if (!verdict || !["ALLOW", "ASK", "BLOCK"].includes(verdict.decision)) {
|
|
401
|
+
return checkerFailure("CHECKER_INVALID_OUTPUT",
|
|
402
|
+
"The checker returned no usable decision. Check the package and recovery state.");
|
|
368
403
|
}
|
|
404
|
+
rt.diagnostics.last_checker_result = "OK";
|
|
369
405
|
if (verdict.decision === "ALLOW") {
|
|
370
406
|
const comps = verdict.compensations || [];
|
|
371
407
|
if (comps.length > 0) {
|
|
@@ -375,6 +411,8 @@ function contribute(ctx, config, rt) {
|
|
|
375
411
|
"check_id=" + (verdict.check_id || "unknown")
|
|
376
412
|
);
|
|
377
413
|
}
|
|
414
|
+
if (verdict.storage_notice) console.log("[agent-guard]", verdict.storage_notice,
|
|
415
|
+
"Use agent_guard_status for usage and GC commands.");
|
|
378
416
|
return next();
|
|
379
417
|
}
|
|
380
418
|
const reasons = Array.isArray(verdict.reasons)
|
|
@@ -403,11 +441,22 @@ function contribute(ctx, config, rt) {
|
|
|
403
441
|
};
|
|
404
442
|
})
|
|
405
443
|
);
|
|
444
|
+
rt.diagnostics.hook_registered = true;
|
|
406
445
|
|
|
407
446
|
// ---- 2) model tools --------------------------------------------------
|
|
408
447
|
function renderJson(_args, value) {
|
|
448
|
+
// Keep diagnostics and storage guidance visible before long target/audit
|
|
449
|
+
// arrays consume the existing model-facing preview budget.
|
|
450
|
+
const display = {
|
|
451
|
+
...(value.adapter ? { adapter: value.adapter } : {}),
|
|
452
|
+
...(value.report?.storage_notice ? {
|
|
453
|
+
storage_notice: value.report.storage_notice,
|
|
454
|
+
gc: value.report.gc,
|
|
455
|
+
} : {}),
|
|
456
|
+
...value,
|
|
457
|
+
};
|
|
409
458
|
return [
|
|
410
|
-
{ type: "text", text: JSON.stringify(
|
|
459
|
+
{ type: "text", text: JSON.stringify(display, null, 2).slice(0, 4000) },
|
|
411
460
|
];
|
|
412
461
|
}
|
|
413
462
|
|
|
@@ -417,6 +466,24 @@ function contribute(ctx, config, rt) {
|
|
|
417
466
|
"Working directory (repo root) for this operation; defaults to the session workspace.",
|
|
418
467
|
};
|
|
419
468
|
|
|
469
|
+
function adapterStatus() {
|
|
470
|
+
return {
|
|
471
|
+
...rt.diagnostics,
|
|
472
|
+
note: "Startup checks the plugin process Python only. Hook registration and a local status result do not verify live host interception or every shell environment.",
|
|
473
|
+
};
|
|
474
|
+
}
|
|
475
|
+
|
|
476
|
+
function statusFailure(diagnostic, detail, exitCode = null) {
|
|
477
|
+
return {
|
|
478
|
+
ok: false,
|
|
479
|
+
exitCode,
|
|
480
|
+
report: null,
|
|
481
|
+
diagnostic,
|
|
482
|
+
stderr: detail,
|
|
483
|
+
adapter: adapterStatus(),
|
|
484
|
+
};
|
|
485
|
+
}
|
|
486
|
+
|
|
420
487
|
function makeTool(name, description, parameterSpec, buildArgs) {
|
|
421
488
|
return {
|
|
422
489
|
name,
|
|
@@ -429,19 +496,44 @@ function contribute(ctx, config, rt) {
|
|
|
429
496
|
execute: async (args, exec) => {
|
|
430
497
|
assertToolArgs(name, parameterSpec, args);
|
|
431
498
|
const plan = buildArgs(args);
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
499
|
+
let result;
|
|
500
|
+
try {
|
|
501
|
+
result = await rt.runScript(
|
|
502
|
+
plan.script,
|
|
503
|
+
plan.argString,
|
|
504
|
+
plan.workdir,
|
|
505
|
+
120000,
|
|
506
|
+
exec
|
|
507
|
+
);
|
|
508
|
+
} catch (error) {
|
|
509
|
+
if (name !== "agent_guard_status") throw error;
|
|
510
|
+
return statusFailure("STATUS_EXECUTION_FAILED",
|
|
511
|
+
"Status could not run in the caller's shell environment. Check Python and the package; adapter diagnostics below remain available.");
|
|
512
|
+
}
|
|
439
513
|
const parsed = rt.parseJson(rt.outText(result.stdout));
|
|
514
|
+
if (name === "agent_guard_status") {
|
|
515
|
+
if (result.timedOut) {
|
|
516
|
+
return statusFailure("STATUS_TIMEOUT",
|
|
517
|
+
"Status timed out. No recovery report is available; inspect the workspace before retrying.", result.exitCode);
|
|
518
|
+
}
|
|
519
|
+
if (result.exitCode !== 0) {
|
|
520
|
+
return statusFailure("STATUS_PROCESS_FAILED",
|
|
521
|
+
"Status exited unsuccessfully. Check Python, the package and recovery data.", result.exitCode);
|
|
522
|
+
}
|
|
523
|
+
if (typeof parsed?.workspace !== "string" || typeof parsed?.mode !== "string" ||
|
|
524
|
+
!Number.isFinite(parsed?.usage?.bytes)) {
|
|
525
|
+
return statusFailure("STATUS_INVALID_OUTPUT",
|
|
526
|
+
"Status returned no usable recovery report. Check the package and caller's shell environment.", result.exitCode);
|
|
527
|
+
}
|
|
528
|
+
}
|
|
440
529
|
return {
|
|
441
530
|
ok: result.exitCode === 0,
|
|
442
531
|
exitCode: result.exitCode,
|
|
443
532
|
report: parsed === undefined ? rt.outText(result.stdout) : parsed,
|
|
444
533
|
stderr: rt.outText(result.stderr).slice(0, 2000),
|
|
534
|
+
...(name === "agent_guard_status" ? {
|
|
535
|
+
adapter: adapterStatus(),
|
|
536
|
+
} : {}),
|
|
445
537
|
};
|
|
446
538
|
},
|
|
447
539
|
};
|
|
@@ -451,7 +543,7 @@ function contribute(ctx, config, rt) {
|
|
|
451
543
|
ctx.tools.register(
|
|
452
544
|
makeTool(
|
|
453
545
|
"agent_guard_status",
|
|
454
|
-
"Show
|
|
546
|
+
"Show adapter diagnostics, recovery mode, quarantine usage and GC commands. Local status does not verify live host interception.",
|
|
455
547
|
{ cwd: CWD_PROP },
|
|
456
548
|
(args) => ({ script: "status.py", argString: "--json", workdir: args.cwd })
|
|
457
549
|
)
|
|
@@ -461,7 +553,7 @@ function contribute(ctx, config, rt) {
|
|
|
461
553
|
ctx.tools.register(
|
|
462
554
|
makeTool(
|
|
463
555
|
"agent_guard_safe_delete",
|
|
464
|
-
"
|
|
556
|
+
"Delete with the existing recovery policy: valuable targets go to quarantine and still use disk space; eligible generated artifacts may be deleted directly. Accepts paths and globs.",
|
|
465
557
|
{
|
|
466
558
|
paths: {
|
|
467
559
|
type: "array",
|
|
@@ -512,22 +604,24 @@ function contribute(ctx, config, rt) {
|
|
|
512
604
|
text: [
|
|
513
605
|
"## Deletion discipline (agent-guard)",
|
|
514
606
|
"",
|
|
515
|
-
"
|
|
607
|
+
"Agent Guard checks supported destructive-looking Bash commands and provides recovery tools. Other tools and scripts may be outside its coverage.",
|
|
516
608
|
"",
|
|
517
|
-
"- To delete files/directories/globs, prefer
|
|
609
|
+
"- To delete files/directories/globs, prefer agent_guard_safe_delete. Valuable targets move to quarantine and still use disk space; eligible generated artifacts may be deleted directly. Pass cwd for the intended repo. Status includes GC planning and explicit purge commands.",
|
|
518
610
|
"- Raw rm / git clean / git reset --hard are intercepted before execution. Most are compensated automatically (relocate or snapshot) and simply proceed; note the txid.",
|
|
519
611
|
"- Shape rules: a command line that cds before deleting (COMPOUND_CWD_DELETE), or creates files and then deletes them (COMPOUND_CREATE_DELETE), triggers a single-execution user authorization. Splitting the deletion into its own standalone command avoids the prompt entirely.",
|
|
520
612
|
"- True effect-uncertainty ($VAR targets, bash -c, find -delete, xargs-fed lists) stays hard-BLOCKED: restating with explicit concrete paths is the only remedy.",
|
|
521
613
|
"- BLOCK_OUT_OF_WORKSPACE, BLOCK_PROTECTED_PATH (.git, workspace root) and BLOCK_FORCE_PUSH are policy violations and never askable: do not retry variants; ask the human if truly needed.",
|
|
522
614
|
"- In RESTRICTED mode only explicit single-file deletes inside the workspace are permitted; only a human can restore NORMAL.",
|
|
523
|
-
"- Never circumvent the guard (no /bin/rm, python os.unlink, node fs.rmSync, relocated scripts).
|
|
615
|
+
"- Never circumvent the guard (no /bin/rm, python os.unlink, node fs.rmSync, relocated scripts). Calls outside the covered path may have no recovery or audit record.",
|
|
524
616
|
"- Undo with agent_guard_restore(txid). Inspect state with agent_guard_status().",
|
|
525
617
|
].join("\n"),
|
|
526
618
|
})
|
|
527
619
|
);
|
|
528
620
|
}
|
|
529
621
|
|
|
622
|
+
console.log("[agent-guard] Hook registered; local Python checker passed. Live host interception is unverified. Inspect agent_guard_status for diagnostics.");
|
|
530
623
|
return () => {
|
|
624
|
+
rt.diagnostics.hook_registered = false;
|
|
531
625
|
while (disposers.length) {
|
|
532
626
|
const d = disposers.pop();
|
|
533
627
|
try {
|
|
@@ -5,6 +5,11 @@ This POSIX helper pins **Kimi Code 2.1.1**, captures prompt mode with
|
|
|
5
5
|
Configuration checks and profile preparation require Python 3.11+ for `tomllib`;
|
|
6
6
|
the shared Guard Core retains its Python 3.9+ floor. No dependency is installed.
|
|
7
7
|
|
|
8
|
+
Start with the [four-control example](../../../docs/lab/blue-team-calibration.md)
|
|
9
|
+
for host-independent calibration. The [defensive research](../../../docs/research/README.md)
|
|
10
|
+
includes separate Node Kimi 0.42.0 observations; they do not change this helper's
|
|
11
|
+
Kimi 2.1.1 version contract.
|
|
12
|
+
|
|
8
13
|
## Private matched homes
|
|
9
14
|
|
|
10
15
|
Select the approved source home and the exact 2.1.1 executable. There may be a
|
package/core/lab.py
CHANGED
|
@@ -772,14 +772,17 @@ def prepare_run(
|
|
|
772
772
|
task_file: Optional[Path] = None,
|
|
773
773
|
attack_sample: str = "direct-v1",
|
|
774
774
|
non_guard_configuration_sha256: Optional[str] = None,
|
|
775
|
+
*,
|
|
776
|
+
_injection_samples: Optional[dict] = None,
|
|
775
777
|
) -> dict[str, Any]:
|
|
778
|
+
samples = INJECTION_SAMPLES if _injection_samples is None else _injection_samples
|
|
776
779
|
if case_id not in CASE_DEFINITIONS:
|
|
777
780
|
raise LabError("unknown lab case")
|
|
778
|
-
if attack_sample not in
|
|
781
|
+
if attack_sample not in samples:
|
|
779
782
|
raise LabError("unknown injection sample")
|
|
780
783
|
if case_id != "injection-probe" and attack_sample != "direct-v1":
|
|
781
784
|
raise LabError("attack samples apply only to injection-probe")
|
|
782
|
-
sample =
|
|
785
|
+
sample = samples[attack_sample]
|
|
783
786
|
sample_identity = {
|
|
784
787
|
"id": attack_sample,
|
|
785
788
|
"template_sha256": _sha256_bytes(_canonical_bytes(sample)),
|
package/core/messages.py
ADDED
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
"""User-facing storage notices; no policy or execution decisions."""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
from pathlib import Path
|
|
5
|
+
import shlex
|
|
6
|
+
import sys
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
QUARANTINE_NOTICE = (
|
|
10
|
+
"Files moved to quarantine still use disk space. "
|
|
11
|
+
"Purging permanently removes their recovery copies."
|
|
12
|
+
)
|
|
13
|
+
|
|
14
|
+
HOST_STATUS_NOTICE = (
|
|
15
|
+
"This reports local recovery data, not whether a host loaded the guard. "
|
|
16
|
+
"Check the host's plugin or hook status separately."
|
|
17
|
+
)
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
def gc_guidance():
|
|
21
|
+
script = Path(__file__).resolve().parent.parent / "skills/delete-guard/scripts/gc.py"
|
|
22
|
+
command = [sys.executable, str(script)]
|
|
23
|
+
return {
|
|
24
|
+
"plan_command": shlex.join(command),
|
|
25
|
+
"purge_eligible_command": shlex.join(
|
|
26
|
+
command + ["--execute", "--all-eligible"]),
|
|
27
|
+
"purge_transaction_command": shlex.join(
|
|
28
|
+
command + ["--execute", "--txid", "<txid>"]),
|
|
29
|
+
"note": "POSIX-shell commands. Review the plan first. Run from the same working directory "
|
|
30
|
+
"with the same AGENT_GUARD_WORKSPACE / AGENT_GUARD_TRASH settings. "
|
|
31
|
+
"Replace <txid> to select one transaction.",
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
def print_gc_guidance(guidance):
|
|
36
|
+
print(f"GC plan : {guidance['plan_command']}")
|
|
37
|
+
print(f"GC purge : {guidance['purge_eligible_command']}")
|
|
38
|
+
print(" permanently removes eligible recovery copies")
|
|
39
|
+
print(f"GC one : {guidance['purge_transaction_command']}")
|
|
40
|
+
print(guidance["note"])
|
package/core/policy.py
CHANGED
|
@@ -122,7 +122,8 @@ CODE_BLOCK_GIT_RESET_COLLISION = "BLOCK_GIT_RESET_COLLISION"
|
|
|
122
122
|
|
|
123
123
|
# Human-facing one-liners: why the guard cannot just do it (or did do it).
|
|
124
124
|
EXPLANATIONS: Dict[str, str] = {
|
|
125
|
-
CODE_ALLOW_NOOP: "
|
|
125
|
+
CODE_ALLOW_NOOP: "No recovery action is needed for the recognized operations. "
|
|
126
|
+
"Unrecognized command effects have not been checked.",
|
|
126
127
|
CODE_ALLOW_REGENERABLE: "All targets are git-ignored and match known "
|
|
127
128
|
"artifact patterns; deleted directly.",
|
|
128
129
|
CODE_ALLOW_TRASH_GC: "Targets live inside the quarantine; housekeeping "
|
package/docs/README.md
CHANGED
|
@@ -7,11 +7,15 @@ setup. The three main paths are [recovery protection](../skills/delete-guard/SKI
|
|
|
7
7
|
[harness capability matrix](guides/harness-capabilities.md) for observed coverage
|
|
8
8
|
and the [architecture](design/architecture.md) for the shared Core.
|
|
9
9
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
publication
|
|
10
|
+
Stable release line: [0.2.5](releases/release-notes-0.2.5.md), combining
|
|
11
|
+
RC1–RC3 and clearer startup, command and storage feedback. The exact
|
|
12
|
+
[GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5)
|
|
13
|
+
and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5)
|
|
14
|
+
establish publication and npm `latest` availability; 0.2.4 is the previous stable.
|
|
15
|
+
The opt-in `rc` line remains [0.2.5-rc3](releases/release-notes-0.2.5-rc3.md), and `hotfix` is the
|
|
16
|
+
opt-in [0.2.4-hotfix.1](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.4-hotfix.1)
|
|
17
|
+
quarantine protection backport. The [getting-started guide](guides/getting-started.md)
|
|
18
|
+
explains exact-version and local-package installation.
|
|
15
19
|
|
|
16
20
|
先看入门指南,再按恢复保护、外发检测、Lab 验测选择入口。测试报告按所测版本与配置保留;发布记录、
|
|
17
21
|
历史设计和外部案例各自归档,不能据此扩展当前产品的承诺。
|
|
@@ -20,20 +24,25 @@ publication is established by its GitHub/npm receipts.
|
|
|
20
24
|
|---|---|
|
|
21
25
|
| [Guides](#guides) / 使用指南 | 宿主接入证据、漂移检查、维护者发布指南 |
|
|
22
26
|
| [Design](#design) / 架构与契约 | 当前架构、威胁模型与兼容契约 |
|
|
23
|
-
| [Lab](#lab) /
|
|
27
|
+
| [Lab](#lab) / 防守验测 | 校准流程、任务模板及历史候选参考 |
|
|
28
|
+
| [Research](#research) / 防守研究 | 来源、发送授权、父子代理与正常任务评分 |
|
|
24
29
|
| [Reports](#reports) / 测试报告 | 按宿主、版本和观察范围记录的证据 |
|
|
25
30
|
| [Releases](#releases) / 发布记录 | 正式版与预览版各自的范围 |
|
|
26
31
|
| [History](#history) / 历史设计与经验 | 早期设计、实现教训和事故探索 |
|
|
27
32
|
|
|
28
33
|
## Guides
|
|
29
34
|
|
|
35
|
+
当前源码中的[状态与清理反馈](guides/recovery-feedback.md)说明本地 Python/Hook/宿主验证的区别、
|
|
36
|
+
ALLOW_NOOP 覆盖边界及准确 GC 用法;纳入 0.2.5。
|
|
37
|
+
|
|
30
38
|
| Document / 文档 | Scope / 范围 |
|
|
31
39
|
|---|---|
|
|
32
40
|
| [Getting started](guides/getting-started.md) | 安装路径、Agent 接入提示词与最短验证流程 |
|
|
41
|
+
| [Status and cleanup feedback](guides/recovery-feedback.md) | Python/插件状态、ALLOW_NOOP、保留空间与手动 GC |
|
|
33
42
|
| [Harness capabilities](guides/harness-capabilities.md) | 当前接入范围、证据等级与未验证路径 |
|
|
34
43
|
| [Host drift](guides/host-drift.md) | 宿主版本、配置与本地基线检查 |
|
|
35
44
|
| [Trash locations](guides/trash-index.md) | 0.2.4 的只读位置查询、Agent/前端共享 JSON 契约 |
|
|
36
|
-
| [Audit metadata](guides/audit-metadata.md) | RC2
|
|
45
|
+
| [Audit metadata](guides/audit-metadata.md) | RC2 引入的字段投影、会话关联、GC/status 契约与保留边界 |
|
|
37
46
|
| [Publishing from ephemeral environments](guides/publishing-from-ephemeral-environments.md) | 临时环境中的 GitHub 发布操作参考 |
|
|
38
47
|
|
|
39
48
|
Adapter setup remains in [adapters/](../adapters/INTEGRATION.md). Skill contracts
|
|
@@ -52,6 +61,7 @@ remain in [skills/](../skills/delete-guard/SKILL.md).
|
|
|
52
61
|
| Document / 文档 | Scope / 范围 |
|
|
53
62
|
|---|---|
|
|
54
63
|
| [Guard Lab guide](lab/guard-lab.md) | 操作流程、信道、L0/L1/L2 语义与限制 |
|
|
64
|
+
| [Blue-team calibration](lab/blue-team-calibration.md) | 可从 checkout/包运行的四种零模型控制 |
|
|
55
65
|
| [Clean task](lab/tasks/guard-lab-clean-task.md) | 干净对照任务模板 |
|
|
56
66
|
| [Injection trial task](lab/tasks/guard-lab-trial-task.md) | 提示注入试次任务模板 |
|
|
57
67
|
| [Native-read trial task](lab/tasks/guard-lab-read-trial-task.md) | 原生读取脱敏任务模板 |
|
|
@@ -61,6 +71,13 @@ Task templates and external case references are separate from completed test
|
|
|
61
71
|
reports. A scripted provider checks host behavior; a real-model injection
|
|
62
72
|
trial needs an effective unguarded baseline before a matched comparison.
|
|
63
73
|
|
|
74
|
+
## Research
|
|
75
|
+
|
|
76
|
+
[研究导航](research/README.md)汇总本项目防守研究的整理稿:
|
|
77
|
+
数据流观察、正文发送授权、父子来源与独立评分。私有实验方法、公开校准入口与生产
|
|
78
|
+
覆盖分别说明。Lab 小规模推进,欢迎 fork、PR 与独立复现;公开资料不包含诱导载荷
|
|
79
|
+
或私有运行原件。
|
|
80
|
+
|
|
64
81
|
## Reports
|
|
65
82
|
|
|
66
83
|
Each report preserves its original version, configuration, result and limits.
|
|
@@ -69,6 +86,7 @@ coverage rather than treating every historical result as current acceptance.
|
|
|
69
86
|
|
|
70
87
|
| Document / 文档 | Scope / 范围 |
|
|
71
88
|
|---|---|
|
|
89
|
+
| [Blue-team Lab, October 2026](reports/blue-team-lab-2026-10.md) | 来源/发送授权/任务效用与失败的去敏阶段摘要;不升级正式证据等级 |
|
|
72
90
|
| [0.2.3 contract review](reports/test-report-release-readiness-0.2.3.md) | 发布前契约复核与 DSH 原生验收 |
|
|
73
91
|
| [0.2.4 official Flash / PTC](reports/test-report-dsh-0.2.4-ptc.md) | 实模主/子代理碰撞拒绝;原始主 PTC 任务失败与独立收尾分别记录 |
|
|
74
92
|
| [Claude Code harness](reports/test-report-claude-code-harness.md) | 脚本模型驱动的真实宿主 hook 验证 |
|
|
@@ -92,7 +110,10 @@ coverage rather than treating every historical result as current acceptance.
|
|
|
92
110
|
|
|
93
111
|
| Document / 文档 | Scope / 范围 |
|
|
94
112
|
|---|---|
|
|
95
|
-
| [0.2.5
|
|
113
|
+
| [0.2.5](releases/release-notes-0.2.5.md) | 正式版范围;累计 RC 维护、明确反馈与升级影响 |
|
|
114
|
+
| [0.2.4-hotfix.1](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.4-hotfix.1) | 已发布的稳定线回收站保护回补;不含完整 RC 累计内容 |
|
|
115
|
+
| [0.2.5-rc3](releases/release-notes-0.2.5-rc3.md) | 已发布的研究/文档预发布版与零模型示例 |
|
|
116
|
+
| [0.2.5-rc2](releases/release-notes-0.2.5-rc2.md) | 已发布的维护 RC;共享审计、observer 维护与兼容边界 |
|
|
96
117
|
| [0.2.5-rc1](releases/release-notes-0.2.5-rc1.md) | 已发布的维护预发布基线、文档整理与版本例外 |
|
|
97
118
|
| [0.2.4](releases/release-notes-0.2.4.md) | 恢复维护、trash 查询及兼容性例外 |
|
|
98
119
|
| [0.2.3](releases/release-notes-0.2.3.md) | 正式版范围与证据边界 |
|
|
@@ -23,7 +23,7 @@ the identity of the project.
|
|
|
23
23
|
| Authorization | Who decides what? | `core/policy.py` (mode state machine) |
|
|
24
24
|
| Auditability | What actually happened? | `core/audit.py` + `.agent-trash/*.jsonl` |
|
|
25
25
|
|
|
26
|
-
|
|
26
|
+
Release 0.2.5-rc2 introduced a shared
|
|
27
27
|
[audit metadata projection](../guides/audit-metadata.md) on append and legacy
|
|
28
28
|
read, with opaque session correlation. Recovery manifests retain exact paths;
|
|
29
29
|
authorization state and required audit durability remain separate contracts.
|
|
@@ -305,10 +305,14 @@ order of value:
|
|
|
305
305
|
|
|
306
306
|
## Delivery status and design directions
|
|
307
307
|
|
|
308
|
-
The
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
308
|
+
The stable release line is 0.2.5. Previous stable 0.2.4, opt-in
|
|
309
|
+
0.2.4-hotfix.1 and prerelease 0.2.5-rc3 retain their separate artifacts.
|
|
310
|
+
Version 0.2.5 retains RC recovery, shared audit,
|
|
311
|
+
observer maintenance and [defensive research](../research/README.md), plus
|
|
312
|
+
clearer local startup/status and retained-storage feedback. Private research
|
|
313
|
+
methods do not add a general authorization service or production enforcement
|
|
314
|
+
point. Deletion rules and execution routes retain their RC behavior.
|
|
315
|
+
See [candidate notes](../releases/release-notes-0.2.5.md) and
|
|
312
316
|
[compatibility](compatibility.md) for behaviour and validation boundaries.
|
|
313
317
|
|
|
314
318
|
The milestones below describe historical delivery and future design scope,
|
|
@@ -4,11 +4,51 @@ agent-guard's promise is recoverability. A promise is only as good as its
|
|
|
4
4
|
stability over time - this page states exactly what may change and what
|
|
5
5
|
may not, per release class.
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
7
|
+
The stable release line is [0.2.5](../releases/release-notes-0.2.5.md), carrying
|
|
8
|
+
the cumulative RC maintenance below. The opt-in prerelease remains
|
|
9
|
+
[0.2.5-rc3](../releases/release-notes-0.2.5-rc3.md), 0.2.4 is the previous stable, and
|
|
10
|
+
[0.2.4-hotfix.1](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.4-hotfix.1)
|
|
11
|
+
is an opt-in quarantine protection backport. Versioned sections retain the
|
|
12
|
+
origin and preparation labels of changes introduced by earlier releases.
|
|
13
|
+
|
|
14
|
+
RC3 publishes defensive research and an example around the existing four
|
|
15
|
+
zero-model controls. Experimental disclosure labels and private delegation
|
|
16
|
+
methods are not additions to the Decision Protocol or native-hook contract.
|
|
17
|
+
No production dependency, policy verdict or storage/configuration migration
|
|
18
|
+
is introduced by the research documentation.
|
|
9
19
|
|
|
10
20
|
## The adapter contract (frozen surface)
|
|
11
21
|
|
|
22
|
+
### 0.2.5 feedback maintenance
|
|
23
|
+
|
|
24
|
+
Deletion rules, wildcard refusal, Decision/reason codes, CLI flags and exit
|
|
25
|
+
roles retain their contracts. `ALLOW_NOOP` receives a clearer explanation;
|
|
26
|
+
human check output displays explanations. Optional `storage_notice`/`gc`
|
|
27
|
+
metadata describes actual retained files and maintenance commands without
|
|
28
|
+
entering the shared audit payload. Status gains a local-versus-host notice.
|
|
29
|
+
|
|
30
|
+
The DSH adapter now checks local Python/checker imports before registration
|
|
31
|
+
and reports startup failure explicitly rather than returning silently when
|
|
32
|
+
shell/script dependencies are missing. This changes plugin lifecycle
|
|
33
|
+
diagnostics, not the Core policy or the host's ability to continue other
|
|
34
|
+
tools. Python must also be available on the plugin process PATH for this
|
|
35
|
+
startup probe. Its scope is the plugin process; live interception remains
|
|
36
|
+
`UNVERIFIED`. Status adds adapter facts and static runtime diagnostics.
|
|
37
|
+
Failed status queries return `ok: false`, `report: null` and `STATUS_*`
|
|
38
|
+
diagnostics for execution failure, timeout, unsuccessful exit or unusable
|
|
39
|
+
reports. Partial relocation failures preserve the existing failure/exit
|
|
40
|
+
semantics and expose their transaction IDs and retained-storage guidance.
|
|
41
|
+
No storage/configuration migration, new dependency or rm execution route is
|
|
42
|
+
introduced. Details are in the [feedback guide](../guides/recovery-feedback.md).
|
|
43
|
+
|
|
44
|
+
The maintainer selected 0.2.5 for the cumulative RC1–RC3 maintenance and this
|
|
45
|
+
feedback work. It carries forward the bounded RC1 maintenance exception
|
|
46
|
+
documented below. Quarantine control-path refusals inherited from RC1 and
|
|
47
|
+
explicit DSH initialization failure are upgrade-visible changes. This choice
|
|
48
|
+
does not permit unrelated verdict changes under the patch versioning rules.
|
|
49
|
+
|
|
50
|
+
### Existing decision surface
|
|
51
|
+
|
|
12
52
|
Harness adapters integrate against exactly four things:
|
|
13
53
|
|
|
14
54
|
1. **Decision classes** - `ALLOW`, `SANITIZE`, `RELOCATE`, `SNAPSHOT`,
|
|
@@ -143,7 +183,7 @@ CLI warnings use stderr; JSON checker stdout and sanitizer payload/plan stdout
|
|
|
143
183
|
keep their respective formats. Normal missing/valid configurations remain
|
|
144
184
|
quiet. Diagnostic codes are configuration metadata, not Decision Protocol
|
|
145
185
|
reason codes. Consumers should tolerate the additive fields and warnings;
|
|
146
|
-
these diagnostics originated in RC1 and
|
|
186
|
+
these diagnostics originated in RC1 and are retained by RC2 and RC3. The diagnostic
|
|
147
187
|
grammar and privacy contract are in [rules.md](../../skills/exfil-guard/references/rules.md#configuration-diagnostics).
|
|
148
188
|
|
|
149
189
|
### 0.2.0 check output minimization
|
|
@@ -8,8 +8,8 @@ bypass. Therefore:
|
|
|
8
8
|
|
|
9
9
|
- agent-guard is **reliability infrastructure**, not a security boundary.
|
|
10
10
|
It defends against *mistakes*: misjudged context, mis-expanded commands,
|
|
11
|
-
wrong working directory
|
|
12
|
-
|
|
11
|
+
wrong working directory and hallucinated paths. It does not cover every
|
|
12
|
+
cause of data loss or every destructive operation.
|
|
13
13
|
- You may claim: recovery for supported valuable deletions, explicit audit
|
|
14
14
|
contracts for observed calls, graded authorization discipline, and reduced
|
|
15
15
|
blast radius of common accidents. Regenerable artifacts may be deleted
|
|
@@ -10,24 +10,40 @@ Agent Guard 提供恢复保护、外发检测和用户控制的行为验测。
|
|
|
10
10
|
|
|
11
11
|
## Select the package root
|
|
12
12
|
|
|
13
|
-
The
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
13
|
+
The stable release line is [0.2.5](../releases/release-notes-0.2.5.md), and the
|
|
14
|
+
prerelease line remains [0.2.5-rc3](../releases/release-notes-0.2.5-rc3.md).
|
|
15
|
+
The optional [0.2.4-hotfix.1](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.4-hotfix.1)
|
|
16
|
+
backports quarantine protection onto the stable line.
|
|
17
|
+
Version 0.2.5 combines RC1–RC3 and clearer status, command and storage feedback.
|
|
18
|
+
Its [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5)
|
|
19
|
+
and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5)
|
|
20
|
+
establish package availability. Use a user-selected stable prefix:
|
|
17
21
|
|
|
18
22
|
```sh
|
|
19
|
-
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.
|
|
23
|
+
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.5
|
|
20
24
|
```
|
|
21
25
|
|
|
22
26
|
The package root is
|
|
23
27
|
`/absolute/path/to/agent-guard-install/node_modules/@mokuyoaxis/agent-guard`.
|
|
24
|
-
|
|
25
|
-
[GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5-
|
|
26
|
-
and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
28
|
+
To select the prerelease, use `@mokuyoaxis/agent-guard@0.2.5-rc3` explicitly;
|
|
29
|
+
its [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5-rc3)
|
|
30
|
+
and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5-rc3)
|
|
31
|
+
identify the published package. For the stable-line fix alone, select
|
|
32
|
+
`@mokuyoaxis/agent-guard@0.2.4-hotfix.1`. These opt-in channels do not move
|
|
33
|
+
stable `latest`.
|
|
34
|
+
|
|
35
|
+
For a reviewed local checkout or explicitly selected local tarball, use a
|
|
36
|
+
separate prefix:
|
|
37
|
+
|
|
38
|
+
```sh
|
|
39
|
+
npm install --offline --ignore-scripts --no-audit --no-fund --prefix /absolute/path/to/agent-guard-review /absolute/path/to/mokuyoaxis-agent-guard-0.2.5.tgz
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
The review package root is
|
|
43
|
+
`/absolute/path/to/agent-guard-review/node_modules/@mokuyoaxis/agent-guard`.
|
|
44
|
+
Keep the selected package/checkout path consistent when configuring the host.
|
|
45
|
+
Do not infer publication from a manifest/main commit or use an unscoped
|
|
46
|
+
same-name package. A checkout's default branch can differ from a tagged stable release.
|
|
31
47
|
|
|
32
48
|
Core needs Python 3.9+ and Git, with no third-party Python packages. POSIX
|
|
33
49
|
examples/bridges require a POSIX shell. The optional pinned DSH read path uses
|
|
@@ -1,10 +1,17 @@
|
|
|
1
1
|
# Harness capability and evidence matrix
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Stable release line: [0.2.5](../releases/release-notes-0.2.5.md).
|
|
4
|
+
It retains RC1–RC3 and adds clearer startup, command and storage
|
|
5
|
+
feedback. Published prerelease, checked on 2026-10-19:
|
|
6
|
+
[0.2.5-rc3](../releases/release-notes-0.2.5-rc3.md).
|
|
4
7
|
Rows below retain their tested source/host versions and do not automatically
|
|
5
|
-
certify
|
|
8
|
+
certify a later release. Local regression or package checks are separate from
|
|
6
9
|
new native-host/model evidence.
|
|
7
10
|
|
|
11
|
+
The new [research notes](../research/README.md) describe bounded private
|
|
12
|
+
experiments; their disclosure/delegation methods do not change the supported
|
|
13
|
+
production coverage in this matrix.
|
|
14
|
+
|
|
8
15
|
The Python Core and CLI are harness-neutral. A Skill or CLI being usable in a
|
|
9
16
|
host does **not** mean that host intercepts tool calls, and an adapter returning
|
|
10
17
|
`BLOCK` does **not** by itself prove the host prevented execution.
|