@mokuyoaxis/agent-guard 0.2.4 → 0.2.5-rc1
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/README.md +158 -574
- package/README.zh-CN.md +133 -490
- package/SECURITY.md +53 -0
- package/adapters/INTEGRATION.md +4 -2
- package/adapters/dsh/README.md +7 -0
- package/assets/linux-do-community.svg +19 -0
- package/core/classifier.py +25 -1
- package/core/policy.py +17 -9
- package/core/recovery.py +5 -1
- package/core/redaction.py +122 -21
- package/docs/README.md +14 -5
- package/docs/design/architecture.md +20 -6
- package/docs/design/compatibility.md +71 -1
- package/docs/design/threat-model.md +6 -4
- package/docs/guides/getting-started.md +104 -0
- package/docs/guides/harness-capabilities.md +5 -0
- package/docs/history/friction.md +84 -0
- package/docs/lab/guard-lab.md +3 -1
- package/docs/releases/release-notes-0.2.5-rc1.md +91 -0
- package/package.json +4 -2
- package/skills/delete-guard/SKILL.md +42 -7
- package/skills/delete-guard/references/policy.md +86 -3
- package/skills/delete-guard/scripts/check.py +3 -0
- package/skills/delete-guard/scripts/restore.py +22 -7
- package/skills/delete-guard/scripts/safe_delete.py +52 -29
- package/skills/exfil-guard/SKILL.md +23 -11
- package/skills/exfil-guard/references/channels.md +8 -1
- package/skills/exfil-guard/references/rules.md +83 -6
- package/skills/exfil-guard/scripts/_payload.py +20 -0
- package/skills/exfil-guard/scripts/check_span.py +5 -1
- package/skills/exfil-guard/scripts/sanitize.py +6 -3
package/SECURITY.md
ADDED
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
# Security policy
|
|
2
|
+
|
|
3
|
+
## Reporting
|
|
4
|
+
|
|
5
|
+
Open a GitHub issue for non-sensitive issues, or contact the maintainer
|
|
6
|
+
directly for anything you believe is exploitable. Please include the
|
|
7
|
+
verdict JSON and audit lines involved.
|
|
8
|
+
|
|
9
|
+
## What agent-guard claims to be
|
|
10
|
+
|
|
11
|
+
Reliability infrastructure: it makes destructive actions reversible by
|
|
12
|
+
default and records evidence. It is **not a security sandbox** - an agent
|
|
13
|
+
with the same OS privileges as the guard can bypass it. See
|
|
14
|
+
[docs/design/threat-model.md](docs/design/threat-model.md) before relying on it.
|
|
15
|
+
|
|
16
|
+
## Expected scanner hits on this repository
|
|
17
|
+
|
|
18
|
+
This repository documents, tests, and demonstrates destructive commands -
|
|
19
|
+
that is its subject matter. Static scanners (including `dsh-plugin-gate`)
|
|
20
|
+
will therefore report hits such as:
|
|
21
|
+
|
|
22
|
+
- `rm_recursive` / command patterns inside `README*`, `docs/`, and
|
|
23
|
+
especially `tests/` fixtures, which must contain real command strings to
|
|
24
|
+
exercise the classifier;
|
|
25
|
+
- `dynamic_require` in `core/policy.py` (the `subprocess` call backing
|
|
26
|
+
`git check-ignore`);
|
|
27
|
+
- credential-adjacent wording in `docs/guides/publishing-from-ephemeral-environments.md`
|
|
28
|
+
(a guide about *avoiding* credential leaks).
|
|
29
|
+
|
|
30
|
+
As of v0.1.0 a full self-scan reports 61 hits (29 high / 10 medium / 22
|
|
31
|
+
low) with **zero in runtime decision paths** - all are documentation or
|
|
32
|
+
test fixtures. If you find a hit outside docs/tests/fixtures, please
|
|
33
|
+
report it.
|
|
34
|
+
|
|
35
|
+
## Data handling
|
|
36
|
+
|
|
37
|
+
The command guards store recovery and audit data locally. The default bucket
|
|
38
|
+
is the workspace's `.agent-trash/`; `AGENT_GUARD_TRASH` can select a custom or
|
|
39
|
+
external bucket. Recovery may also write Git metadata, including local exclude
|
|
40
|
+
rules and retained stashes. Linked worktrees can share Git metadata outside
|
|
41
|
+
the selected worktree. Diagnostics and Lab commands use their declared output
|
|
42
|
+
locations. A dry-run assessment can still write metadata.
|
|
43
|
+
|
|
44
|
+
There is no automatic telemetry. Built-in Lab controls call no model and use
|
|
45
|
+
only bounded loopback observation. Explicit live-host/model tests can contact
|
|
46
|
+
the configured provider through the host and consume quota; they are separate
|
|
47
|
+
from local command checks and require a selected experiment scope.
|
|
48
|
+
|
|
49
|
+
Recovery manifests, CLI diagnostics and historical audit records can contain
|
|
50
|
+
exact paths or other private text. Audit minimization in the 0.2.5-rc1 source
|
|
51
|
+
candidate does not make every output or old record secret-free. The exfil text
|
|
52
|
+
CLIs return decisions/plans or sanitized stdout; they do not automatically
|
|
53
|
+
persist egress audit events. Review and redact evidence before sharing it.
|
package/adapters/INTEGRATION.md
CHANGED
|
@@ -42,8 +42,10 @@ call. It must never silently become allow. Treat malformed payloads and
|
|
|
42
42
|
adapter failures conservatively **when the adapter is invoked**; this does
|
|
43
43
|
not protect a call when the host never starts the hook. For a shell tool,
|
|
44
44
|
`check.py --enforce` may relocate files or snapshot Git state, so use it only
|
|
45
|
-
in an authorized execution path
|
|
46
|
-
|
|
45
|
+
in an authorized execution path. Advisory mode assesses without changing
|
|
46
|
+
command targets, but may initialize quarantine/audit metadata and a Git local
|
|
47
|
+
exclude rule. Its exit 0 does not authorize a BLOCK or ASK decision. See the
|
|
48
|
+
[assessment contract](../skills/delete-guard/references/policy.md#assessment-and-dry-run-side-effects).
|
|
47
49
|
|
|
48
50
|
## 3. Configure and verify without destructive trials
|
|
49
51
|
|
package/adapters/dsh/README.md
CHANGED
|
@@ -129,6 +129,13 @@ is forwarded verbatim rather than swapped for POSIX, so `check.py` returns
|
|
|
129
129
|
|
|
130
130
|
## Notes
|
|
131
131
|
|
|
132
|
+
The [0.2.4 official Flash/PTC report](../../docs/reports/test-report-dsh-0.2.4-ptc.md)
|
|
133
|
+
also observed sampled root/child SDK Bash collision refusals. Its original root
|
|
134
|
+
PTC task failed; a separate summary completed. This does not establish general
|
|
135
|
+
PTC Node API mediation or injection L2. The 0.2.5-rc1 documentation update adds
|
|
136
|
+
no new native-host/model result; use the
|
|
137
|
+
[capability matrix](../../docs/guides/harness-capabilities.md) for the full scope.
|
|
138
|
+
|
|
132
139
|
- Deletion commands inherit the caller's sandbox policy per invocation
|
|
133
140
|
(`exec.agent.session`) through the native shell executor.
|
|
134
141
|
- Once the adapter has registered its pre-execute listener, Core process and
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" width="1000" height="160" viewBox="0 0 1000 160" role="img" aria-labelledby="title desc">
|
|
2
|
+
<title id="title">LINUX DO community link</title>
|
|
3
|
+
<desc id="desc">A project-made banner linking to the LINUX DO community, not an official endorsement.</desc>
|
|
4
|
+
<defs>
|
|
5
|
+
<linearGradient id="background" x2="1" y2="1">
|
|
6
|
+
<stop offset="0" stop-color="#111827"/>
|
|
7
|
+
<stop offset="1" stop-color="#263b55"/>
|
|
8
|
+
</linearGradient>
|
|
9
|
+
</defs>
|
|
10
|
+
<rect width="1000" height="160" rx="18" fill="url(#background)"/>
|
|
11
|
+
<rect x="0" y="0" width="12" height="160" rx="6" fill="#f59e0b"/>
|
|
12
|
+
<rect x="40" y="33" width="11" height="11" fill="#f59e0b"/>
|
|
13
|
+
<rect x="55" y="33" width="11" height="11" fill="#f59e0b"/>
|
|
14
|
+
<rect x="40" y="48" width="11" height="11" fill="#f59e0b"/>
|
|
15
|
+
<rect x="55" y="48" width="11" height="11" fill="#f59e0b"/>
|
|
16
|
+
<text x="86" y="79" fill="#ffffff" font-family="Arial, Helvetica, sans-serif" font-size="49" font-weight="700" letter-spacing="2">LINUX DO</text>
|
|
17
|
+
<text x="87" y="115" fill="#cbd5e1" font-family="Arial, Helvetica, sans-serif" font-size="22">COMMUNITY LINK · 社区友链</text>
|
|
18
|
+
<path d="M790 80h145m-27-27 27 27-27 27" fill="none" stroke="#f59e0b" stroke-width="5" stroke-linecap="round" stroke-linejoin="round"/>
|
|
19
|
+
</svg>
|
package/core/classifier.py
CHANGED
|
@@ -33,7 +33,7 @@ import shlex
|
|
|
33
33
|
from dataclasses import dataclass, field
|
|
34
34
|
from typing import List, Optional, Tuple
|
|
35
35
|
|
|
36
|
-
from . import dialects
|
|
36
|
+
from . import AUDIT_NAME, MANIFEST_NAME, STATE_NAME, dialects
|
|
37
37
|
|
|
38
38
|
# ---------------------------------------------------------------- vocabulary
|
|
39
39
|
|
|
@@ -192,6 +192,7 @@ class PathSpec:
|
|
|
192
192
|
inside_trash: bool = False
|
|
193
193
|
protected: Optional[str] = None # None | ancestor-root | workspace-root
|
|
194
194
|
# | outside-workspace | git-metadata
|
|
195
|
+
# | quarantine-control
|
|
195
196
|
error: Optional[str] = None
|
|
196
197
|
|
|
197
198
|
# ------------------------------------------------------------- path analysis
|
|
@@ -250,6 +251,26 @@ def _physical_keep_final(path: str) -> str:
|
|
|
250
251
|
return os.path.join(os.path.realpath(parent), name)
|
|
251
252
|
|
|
252
253
|
|
|
254
|
+
def _quarantine_control_path(absolute: str, physical: str,
|
|
255
|
+
trash_root: str, trash_physical: str,
|
|
256
|
+
workspace: str) -> bool:
|
|
257
|
+
"""Protect storage access and root metadata, retaining leaf-link location."""
|
|
258
|
+
# A configured final link is also the access path to an external bucket.
|
|
259
|
+
# Deleting its parent would sever that access even if storage is elsewhere.
|
|
260
|
+
if (inside_path(physical, workspace) and
|
|
261
|
+
any(inside_path(storage, physical) for storage in
|
|
262
|
+
(trash_physical, _physical_keep_final(trash_root)))):
|
|
263
|
+
return True
|
|
264
|
+
controls = {MANIFEST_NAME, AUDIT_NAME, STATE_NAME, STATE_NAME + ".tmp",
|
|
265
|
+
"sessions"}
|
|
266
|
+
for candidate in (physical, _physical_keep_final(absolute)):
|
|
267
|
+
if inside_path(candidate, trash_physical):
|
|
268
|
+
relative = os.path.relpath(candidate, trash_physical)
|
|
269
|
+
if relative.split(os.sep)[0] in controls:
|
|
270
|
+
return True
|
|
271
|
+
return False
|
|
272
|
+
|
|
273
|
+
|
|
253
274
|
def workspace_boundary_root(workspace: str) -> str:
|
|
254
275
|
"""Physical form of a workspace root, for callers that compare roots."""
|
|
255
276
|
return _physical(os.path.normpath(os.path.abspath(workspace)))
|
|
@@ -365,6 +386,9 @@ def classify_paths(
|
|
|
365
386
|
# content. `rm -rf .` stays a hard BLOCK. (When no trash_root is
|
|
366
387
|
# given, trash_physical is None and cannot match a real path.)
|
|
367
388
|
spec.protected = "workspace-root"
|
|
389
|
+
elif trash_root and _quarantine_control_path(
|
|
390
|
+
absolute, physical, trash_root, trash_physical, workspace):
|
|
391
|
+
spec.protected = "quarantine-control"
|
|
368
392
|
elif not spec.inside_workspace:
|
|
369
393
|
spec.protected = "outside-workspace"
|
|
370
394
|
else:
|
package/core/policy.py
CHANGED
|
@@ -166,8 +166,10 @@ EXPLANATIONS: Dict[str, str] = {
|
|
|
166
166
|
"/usr, /etc, ...), regardless of the "
|
|
167
167
|
"workspace setting. Hard boundary - not "
|
|
168
168
|
"askable.",
|
|
169
|
-
CODE_BLOCK_PROTECTED_PATH: "Target is
|
|
170
|
-
"
|
|
169
|
+
CODE_BLOCK_PROTECTED_PATH: "Target is a protected workspace, Git or "
|
|
170
|
+
"quarantine control path. Hard boundary - "
|
|
171
|
+
"not askable; quarantine transaction cleanup "
|
|
172
|
+
"uses the explicit GC entry point.",
|
|
171
173
|
CODE_BLOCK_WILDCARD: "Glob target sets are opaque; use safe_delete, "
|
|
172
174
|
"which expands globs explicitly.",
|
|
173
175
|
CODE_BLOCK_RESTRICTED_MODE: "This session is in RESTRICTED mode; the "
|
|
@@ -497,7 +499,20 @@ def decide_path_batch(specs: List[PathSpec], ctx: PolicyContext,
|
|
|
497
499
|
[f"protected filesystem root: {s.raw}"
|
|
498
500
|
for s in protected_ancestor[:5]])
|
|
499
501
|
|
|
502
|
+
# Housekeeping never overrides root, control-file or Git protection.
|
|
503
|
+
protected_other = [s for s in specs
|
|
504
|
+
if s.protected in ("workspace-root", "git-metadata",
|
|
505
|
+
"quarantine-control")]
|
|
506
|
+
if protected_other:
|
|
507
|
+
return Verdict(DECISION_BLOCK, CODE_BLOCK_PROTECTED_PATH,
|
|
508
|
+
[f"protected: {s.protected} ({s.raw})"
|
|
509
|
+
for s in protected_other[:5]])
|
|
510
|
+
|
|
500
511
|
if specs and all(s.inside_trash for s in specs):
|
|
512
|
+
if any(s.wildcard for s in specs):
|
|
513
|
+
return Verdict(DECISION_BLOCK, CODE_BLOCK_WILDCARD,
|
|
514
|
+
["quarantine globs may include protected evidence; "
|
|
515
|
+
"enumerate explicitly with safe_delete"])
|
|
501
516
|
return Verdict(DECISION_ALLOW, CODE_ALLOW_TRASH_GC)
|
|
502
517
|
|
|
503
518
|
protected_outside = [s for s in specs
|
|
@@ -507,13 +522,6 @@ def decide_path_batch(specs: List[PathSpec], ctx: PolicyContext,
|
|
|
507
522
|
[f"outside workspace boundary: {s.raw}"
|
|
508
523
|
for s in protected_outside[:5]])
|
|
509
524
|
|
|
510
|
-
protected_other = [s for s in specs
|
|
511
|
-
if s.protected in ("workspace-root", "git-metadata")]
|
|
512
|
-
if protected_other:
|
|
513
|
-
return Verdict(DECISION_BLOCK, CODE_BLOCK_PROTECTED_PATH,
|
|
514
|
-
[f"protected: {s.protected} ({s.raw})"
|
|
515
|
-
for s in protected_other[:5]])
|
|
516
|
-
|
|
517
525
|
wild = [s for s in specs if s.wildcard]
|
|
518
526
|
if wild:
|
|
519
527
|
return Verdict(DECISION_BLOCK, CODE_BLOCK_WILDCARD,
|
package/core/recovery.py
CHANGED
|
@@ -831,9 +831,13 @@ class RecoveryEngine:
|
|
|
831
831
|
return None
|
|
832
832
|
|
|
833
833
|
def tx_inventory(self) -> List[Dict[str, Any]]:
|
|
834
|
-
"""
|
|
834
|
+
"""Active transaction age/size facts; purged history stays in the manifest."""
|
|
835
835
|
inventory: List[Dict[str, Any]] = []
|
|
836
836
|
for txid, tx in self.transactions().items():
|
|
837
|
+
# A tombstone ends our ownership for planning. A directory later
|
|
838
|
+
# recreated under this ID is unmanaged, not another purge target.
|
|
839
|
+
if tx.get("purged"):
|
|
840
|
+
continue
|
|
837
841
|
tx_dir = os.path.join(self.trash_root, txid)
|
|
838
842
|
total = 0
|
|
839
843
|
for root, _dirs, names in os.walk(tx_dir):
|
package/core/redaction.py
CHANGED
|
@@ -896,6 +896,7 @@ class ScanResult:
|
|
|
896
896
|
truncated: bool = False
|
|
897
897
|
size_bytes: int = 0
|
|
898
898
|
exempted: int = 0
|
|
899
|
+
exemption_info: Dict[str, Any] = field(default_factory=dict)
|
|
899
900
|
|
|
900
901
|
@property
|
|
901
902
|
def found(self) -> bool:
|
|
@@ -1006,6 +1007,29 @@ def _secret_source_reference(text: str) -> Optional[Tuple[str, int, int, str]]:
|
|
|
1006
1007
|
|
|
1007
1008
|
DEFAULT_ALLOWFILE = ".agent-guard/exfil-allow.toml"
|
|
1008
1009
|
DEFAULT_IGNOREFILE = ".agent-guardignore"
|
|
1010
|
+
EXEMPTION_DIAGNOSTIC_LIMIT = 32
|
|
1011
|
+
EXEMPTION_DIAGNOSTICS = {
|
|
1012
|
+
"EXEMPTION_IGNORED_LINE": "Line has no assignment or preceding value key; gitignore syntax is unsupported.",
|
|
1013
|
+
"EXEMPTION_UNKNOWN_KEY": "Unknown top-level key; its values are ignored.",
|
|
1014
|
+
"EXEMPTION_UNKNOWN_SECTION": "Unknown section; recognized legacy keys may still apply.",
|
|
1015
|
+
"EXEMPTION_LEGACY_SECTION_KEY": "Nonstandard key uses the legacy section fallback; its values still apply.",
|
|
1016
|
+
"EXEMPTION_MALFORMED_SECTION": "Malformed section header uses legacy parsing; inspect the configuration.",
|
|
1017
|
+
"EXEMPTION_INVALID_HASH": "Value is not a lowercase sha256 digest of 64 hexadecimal characters; it cannot match.",
|
|
1018
|
+
"EXEMPTION_UNSUPPORTED_NEGATION": "Leading ! is a literal pattern character, not gitignore negation.",
|
|
1019
|
+
"EXEMPTION_READ_FAILED": "Configuration could not be read; the next candidate is tried.",
|
|
1020
|
+
"EXEMPTION_ENCODING_INVALID": "Configuration is not UTF-8; the next candidate is tried.",
|
|
1021
|
+
"EXEMPTION_SHADOWED": "This file is not loaded because the preferred file was readable, even if empty or malformed.",
|
|
1022
|
+
}
|
|
1023
|
+
_EXEMPTION_RULE_KEYS = frozenset({"rule", "rules", "disable"})
|
|
1024
|
+
_EXEMPTION_PATH_KEYS = frozenset({"path", "paths", "ignore"})
|
|
1025
|
+
_EXEMPTION_HASH_KEYS = frozenset({"sha256", "hash", "hashes"})
|
|
1026
|
+
|
|
1027
|
+
|
|
1028
|
+
def _safe_exemption_source(source: str) -> Optional[str]:
|
|
1029
|
+
"""Only fixed workspace-relative filenames may leave the process."""
|
|
1030
|
+
if source in (DEFAULT_ALLOWFILE, DEFAULT_IGNOREFILE):
|
|
1031
|
+
return source
|
|
1032
|
+
return "<provided>" if source else None
|
|
1009
1033
|
|
|
1010
1034
|
|
|
1011
1035
|
@dataclass
|
|
@@ -1016,6 +1040,41 @@ class Exemption:
|
|
|
1016
1040
|
paths: List[str] = field(default_factory=list)
|
|
1017
1041
|
hashes: List[str] = field(default_factory=list)
|
|
1018
1042
|
source: str = ""
|
|
1043
|
+
diagnostics: List[Dict[str, Any]] = field(default_factory=list)
|
|
1044
|
+
diagnostics_omitted: int = 0
|
|
1045
|
+
|
|
1046
|
+
def diagnose(self, code: str, source: str, line: int = 0) -> None:
|
|
1047
|
+
"""Bounded, static diagnostics; never copy keys, values or exceptions."""
|
|
1048
|
+
if code not in EXEMPTION_DIAGNOSTICS:
|
|
1049
|
+
return
|
|
1050
|
+
if len(self.diagnostics) >= EXEMPTION_DIAGNOSTIC_LIMIT:
|
|
1051
|
+
self.diagnostics_omitted += 1
|
|
1052
|
+
return
|
|
1053
|
+
row = {"code": code, "source": _safe_exemption_source(source)}
|
|
1054
|
+
if type(line) is int and line > 0:
|
|
1055
|
+
row["line"] = line
|
|
1056
|
+
self.diagnostics.append(row)
|
|
1057
|
+
|
|
1058
|
+
def safe(self) -> Dict[str, Any]:
|
|
1059
|
+
"""Provenance and counts, never the exemption patterns or hashes."""
|
|
1060
|
+
rows = []
|
|
1061
|
+
for row in self.diagnostics[:EXEMPTION_DIAGNOSTIC_LIMIT]:
|
|
1062
|
+
code = row.get("code")
|
|
1063
|
+
if code not in EXEMPTION_DIAGNOSTICS:
|
|
1064
|
+
continue
|
|
1065
|
+
safe = {"code": code,
|
|
1066
|
+
"source": _safe_exemption_source(row.get("source", ""))}
|
|
1067
|
+
if type(row.get("line")) is int and row["line"] > 0:
|
|
1068
|
+
safe["line"] = row["line"]
|
|
1069
|
+
rows.append(safe)
|
|
1070
|
+
return {
|
|
1071
|
+
"source": _safe_exemption_source(self.source),
|
|
1072
|
+
"active": self.active,
|
|
1073
|
+
"counts": {"rules": len(self.rules), "paths": len(self.paths),
|
|
1074
|
+
"hashes": len(self.hashes)},
|
|
1075
|
+
"diagnostics": rows,
|
|
1076
|
+
"diagnostics_omitted": self.diagnostics_omitted,
|
|
1077
|
+
}
|
|
1019
1078
|
|
|
1020
1079
|
@property
|
|
1021
1080
|
def active(self) -> bool:
|
|
@@ -1059,35 +1118,51 @@ def _parse_allowfile(text: str, source: str) -> Exemption:
|
|
|
1059
1118
|
|
|
1060
1119
|
Continuation lines are supported: a key whose value starts on its own
|
|
1061
1120
|
line keeps consuming the indented lines that follow, which is how the
|
|
1062
|
-
lists in `.agent-guard/exfil-allow.toml` stay readable.
|
|
1063
|
-
|
|
1064
|
-
|
|
1121
|
+
lists in `.agent-guard/exfil-allow.toml` stay readable. Preserve legacy
|
|
1122
|
+
matching while diagnosing ignored or nonstandard constructs. Warnings
|
|
1123
|
+
are not whole-file rejection; recognized entries can still apply.
|
|
1065
1124
|
"""
|
|
1066
1125
|
exemption = Exemption(source=source)
|
|
1067
1126
|
section = ""
|
|
1068
1127
|
key = ""
|
|
1069
|
-
values: List[str] = []
|
|
1128
|
+
values: List[Tuple[str, int]] = []
|
|
1129
|
+
key_line = 0
|
|
1070
1130
|
|
|
1071
1131
|
def flush():
|
|
1072
1132
|
if not key:
|
|
1073
1133
|
return
|
|
1074
|
-
|
|
1075
|
-
|
|
1076
|
-
|
|
1077
|
-
|
|
1078
|
-
|
|
1079
|
-
|
|
1080
|
-
|
|
1081
|
-
|
|
1082
|
-
|
|
1134
|
+
if key in _EXEMPTION_RULE_KEYS or section == "rules":
|
|
1135
|
+
target = exemption.rules
|
|
1136
|
+
elif key in _EXEMPTION_PATH_KEYS or section == "paths":
|
|
1137
|
+
target = exemption.paths
|
|
1138
|
+
elif key in _EXEMPTION_HASH_KEYS or section == "values":
|
|
1139
|
+
target = exemption.hashes
|
|
1140
|
+
else:
|
|
1141
|
+
exemption.diagnose("EXEMPTION_UNKNOWN_KEY", source, key_line)
|
|
1142
|
+
return
|
|
1143
|
+
if key not in (_EXEMPTION_RULE_KEYS | _EXEMPTION_PATH_KEYS |
|
|
1144
|
+
_EXEMPTION_HASH_KEYS):
|
|
1145
|
+
exemption.diagnose("EXEMPTION_LEGACY_SECTION_KEY", source, key_line)
|
|
1146
|
+
for value, line in values:
|
|
1147
|
+
if not value.strip("'\""):
|
|
1148
|
+
continue
|
|
1149
|
+
item = value.strip().strip("'\"")
|
|
1150
|
+
target.append(item)
|
|
1151
|
+
if target is exemption.hashes:
|
|
1152
|
+
if not re.fullmatch(r"sha256:[0-9a-f]{64}", item):
|
|
1153
|
+
exemption.diagnose("EXEMPTION_INVALID_HASH", source, line)
|
|
1154
|
+
elif item.startswith("!"):
|
|
1155
|
+
exemption.diagnose("EXEMPTION_UNSUPPORTED_NEGATION", source, line)
|
|
1156
|
+
|
|
1157
|
+
def push(raw: str, line: int):
|
|
1083
1158
|
"""Split one value chunk on commas/whitespace, ignoring [] and ''."""
|
|
1084
1159
|
chunk = raw.strip().strip("[]")
|
|
1085
1160
|
for item in re.split(r"[,\s]+", chunk):
|
|
1086
1161
|
item = item.strip().strip("'\"")
|
|
1087
1162
|
if item:
|
|
1088
|
-
values.append(item)
|
|
1163
|
+
values.append((item, line))
|
|
1089
1164
|
|
|
1090
|
-
for raw_line in text.splitlines():
|
|
1165
|
+
for line_number, raw_line in enumerate(text.splitlines(), 1):
|
|
1091
1166
|
line = raw_line.split("#", 1)[0].rstrip()
|
|
1092
1167
|
if not line.strip():
|
|
1093
1168
|
continue
|
|
@@ -1095,32 +1170,57 @@ def _parse_allowfile(text: str, source: str) -> Exemption:
|
|
|
1095
1170
|
flush()
|
|
1096
1171
|
key, values = "", []
|
|
1097
1172
|
section = line.strip().strip("[]").strip().lower()
|
|
1173
|
+
if not re.fullmatch(r"\[[^\[\]]+\]", line.strip()):
|
|
1174
|
+
exemption.diagnose("EXEMPTION_MALFORMED_SECTION", source, line_number)
|
|
1175
|
+
if section not in ("rules", "paths", "values"):
|
|
1176
|
+
exemption.diagnose("EXEMPTION_UNKNOWN_SECTION", source, line_number)
|
|
1098
1177
|
continue
|
|
1099
1178
|
if "=" in line:
|
|
1100
1179
|
flush()
|
|
1101
1180
|
values = []
|
|
1102
1181
|
key, _, value = line.partition("=")
|
|
1103
1182
|
key = key.strip().lower()
|
|
1104
|
-
|
|
1183
|
+
key_line = line_number
|
|
1184
|
+
if not key:
|
|
1185
|
+
exemption.diagnose("EXEMPTION_UNKNOWN_KEY", source, line_number)
|
|
1186
|
+
push(value, line_number)
|
|
1105
1187
|
continue
|
|
1106
1188
|
if key:
|
|
1107
|
-
push(line)
|
|
1189
|
+
push(line, line_number)
|
|
1190
|
+
else:
|
|
1191
|
+
exemption.diagnose("EXEMPTION_IGNORED_LINE", source, line_number)
|
|
1108
1192
|
flush()
|
|
1109
1193
|
return exemption
|
|
1110
1194
|
|
|
1111
1195
|
|
|
1112
1196
|
def load_exemption(workspace: Optional[str]) -> Exemption:
|
|
1113
1197
|
"""Read the repo-local exemption file; absent means "no exemptions"."""
|
|
1198
|
+
result = Exemption()
|
|
1114
1199
|
if not workspace:
|
|
1115
|
-
return
|
|
1200
|
+
return result
|
|
1116
1201
|
for relative in (DEFAULT_ALLOWFILE, DEFAULT_IGNOREFILE):
|
|
1117
1202
|
path = os.path.join(workspace, relative)
|
|
1118
1203
|
try:
|
|
1119
1204
|
with open(path, "r", encoding="utf-8") as fh:
|
|
1120
|
-
|
|
1121
|
-
except
|
|
1205
|
+
parsed = _parse_allowfile(fh.read(), relative)
|
|
1206
|
+
except FileNotFoundError:
|
|
1122
1207
|
continue
|
|
1123
|
-
|
|
1208
|
+
except UnicodeDecodeError:
|
|
1209
|
+
result.diagnose("EXEMPTION_ENCODING_INVALID", relative)
|
|
1210
|
+
continue
|
|
1211
|
+
except OSError:
|
|
1212
|
+
result.diagnose("EXEMPTION_READ_FAILED", relative)
|
|
1213
|
+
continue
|
|
1214
|
+
result.rules, result.paths, result.hashes = parsed.rules, parsed.paths, parsed.hashes
|
|
1215
|
+
result.source = parsed.source
|
|
1216
|
+
for row in parsed.diagnostics:
|
|
1217
|
+
result.diagnose(row["code"], relative, row.get("line", 0))
|
|
1218
|
+
result.diagnostics_omitted += parsed.diagnostics_omitted
|
|
1219
|
+
if relative == DEFAULT_ALLOWFILE and os.path.lexists(
|
|
1220
|
+
os.path.join(workspace, DEFAULT_IGNOREFILE)):
|
|
1221
|
+
result.diagnose("EXEMPTION_SHADOWED", DEFAULT_IGNOREFILE)
|
|
1222
|
+
return result
|
|
1223
|
+
return result
|
|
1124
1224
|
|
|
1125
1225
|
|
|
1126
1226
|
def apply_exemption(spans: List[SpanSpec], exemption: Exemption,
|
|
@@ -1189,6 +1289,7 @@ def scan_text(text: str, channel: str = "",
|
|
|
1189
1289
|
notes=["value-free reference detection", reason]))
|
|
1190
1290
|
if exemption is None:
|
|
1191
1291
|
exemption = load_exemption(workspace)
|
|
1292
|
+
result.exemption_info = exemption.safe()
|
|
1192
1293
|
# A source-reference fact must survive even inside a redaction span:
|
|
1193
1294
|
# masking a literal URI password is not permission to resolve an env
|
|
1194
1295
|
# secret embedded there. The aggregate BLOCK prevents plan application.
|
package/docs/README.md
CHANGED
|
@@ -1,10 +1,17 @@
|
|
|
1
1
|
# Documentation / 文档导航
|
|
2
2
|
|
|
3
|
-
Start with
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
3
|
+
Start with [getting started](guides/getting-started.md) for installation and
|
|
4
|
+
setup. The three main paths are [recovery protection](../skills/delete-guard/SKILL.md),
|
|
5
|
+
[disclosure checks](../skills/exfil-guard/SKILL.md), and
|
|
6
|
+
[behaviour experiments](lab/guard-lab.md). Use the
|
|
7
|
+
[harness capability matrix](guides/harness-capabilities.md) for observed coverage
|
|
8
|
+
and the [architecture](design/architecture.md) for the shared Core.
|
|
9
|
+
|
|
10
|
+
Current source: [0.2.5-rc1 candidate](releases/release-notes-0.2.5-rc1.md).
|
|
11
|
+
Published stable baseline: [0.2.4](releases/release-notes-0.2.4.md).
|
|
12
|
+
Candidate preparation and package validation do not establish publication.
|
|
13
|
+
|
|
14
|
+
先看入门指南,再按恢复保护、外发检测、Lab 验测选择入口。测试报告按所测版本与配置保留;发布记录、
|
|
8
15
|
历史设计和外部案例各自归档,不能据此扩展当前产品的承诺。
|
|
9
16
|
|
|
10
17
|
| Category / 分类 | Contents / 内容 |
|
|
@@ -20,6 +27,7 @@ Core, and the [Lab guide](lab/guard-lab.md) for experiment semantics.
|
|
|
20
27
|
|
|
21
28
|
| Document / 文档 | Scope / 范围 |
|
|
22
29
|
|---|---|
|
|
30
|
+
| [Getting started](guides/getting-started.md) | 安装路径、Agent 接入提示词与最短验证流程 |
|
|
23
31
|
| [Harness capabilities](guides/harness-capabilities.md) | 当前接入范围、证据等级与未验证路径 |
|
|
24
32
|
| [Host drift](guides/host-drift.md) | 宿主版本、配置与本地基线检查 |
|
|
25
33
|
| [Trash locations](guides/trash-index.md) | 0.2.4 的只读位置查询、Agent/前端共享 JSON 契约 |
|
|
@@ -81,6 +89,7 @@ coverage rather than treating every historical result as current acceptance.
|
|
|
81
89
|
|
|
82
90
|
| Document / 文档 | Scope / 范围 |
|
|
83
91
|
|---|---|
|
|
92
|
+
| [0.2.5-rc1](releases/release-notes-0.2.5-rc1.md) | 当前维护候选、文档整理、版本例外与验收状态 |
|
|
84
93
|
| [0.2.4](releases/release-notes-0.2.4.md) | 恢复维护、trash 查询及兼容性例外 |
|
|
85
94
|
| [0.2.3](releases/release-notes-0.2.3.md) | 正式版范围与证据边界 |
|
|
86
95
|
| [0.2.3-rc2](releases/release-notes-0.2.3-rc2.md) | 离线 Lab 与已复核 DSH 契约 |
|
|
@@ -263,8 +263,11 @@ FORBIDDEN (BLOCK, never askable).
|
|
|
263
263
|
5. **Lexical boundaries.** Workspace containment is decided on normalized
|
|
264
264
|
paths; deleting a symlink removes the link, never the target, so symlink
|
|
265
265
|
targets outside the workspace neither leak nor block.
|
|
266
|
-
6. **Self-exclusion
|
|
267
|
-
quarantine
|
|
266
|
+
6. **Self-exclusion with protected controls.** Ordinary unprotected payloads
|
|
267
|
+
inside the selected quarantine use housekeeping rather than relocation.
|
|
268
|
+
The 0.2.5-rc1 candidate checks root/control paths and storage parents first;
|
|
269
|
+
housekeeping cannot override protection. Opaque globs must be enumerated
|
|
270
|
+
explicitly, and validated transaction purge uses the GC CLI.
|
|
268
271
|
7. **Diagnostics do not silently become enforcement.** `guard-lab` records
|
|
269
272
|
declared synthetic channels and evaluates one case criterion. It does not
|
|
270
273
|
feed a Lab observation into Core policy or claim to ban model calls. A real
|
|
@@ -295,7 +298,17 @@ order of value:
|
|
|
295
298
|
skill and the "prefer safe_delete" rule. Interception without prompting
|
|
296
299
|
causes friction; prompting without interception is advisory only.
|
|
297
300
|
|
|
298
|
-
##
|
|
301
|
+
## Delivery status and design directions
|
|
302
|
+
|
|
303
|
+
The current source candidate is 0.2.5-rc1; 0.2.4 remains the published stable
|
|
304
|
+
baseline. The candidate contains the documented lifecycle/audit maintenance
|
|
305
|
+
and exemption diagnostics, alongside a README/documentation reorganization.
|
|
306
|
+
See [candidate notes](../releases/release-notes-0.2.5-rc1.md) and
|
|
307
|
+
[compatibility](compatibility.md) for behaviour and validation boundaries.
|
|
308
|
+
|
|
309
|
+
The milestones below describe historical delivery and future design scope,
|
|
310
|
+
not a committed schedule or a guarantee that new compensation types need no
|
|
311
|
+
architecture changes.
|
|
299
312
|
|
|
300
313
|
- V1 (this repo): delete-guard skill, fs + git compensations, Linux/macOS.
|
|
301
314
|
- v0.1.1: durable relocation intents, explicit retention/GC policy, quoted
|
|
@@ -315,7 +328,7 @@ order of value:
|
|
|
315
328
|
`tests/test_dialect_phase2.py`) cover further cmd/PowerShell spellings,
|
|
316
329
|
option aliases and fail-closed edge cases. Hook payload dialect forwarding
|
|
317
330
|
has adapter tests; this is not a Windows host execution claim.
|
|
318
|
-
- **Phase 3a (`0.2.3-rc1`
|
|
331
|
+
- **Phase 3a (shipped since `0.2.3-rc1`).** A blocking `windows-latest` Core
|
|
319
332
|
job covers the Issue #7 dialect-mismatch and separator regressions,
|
|
320
333
|
deterministic cmd/PowerShell facts, and recovery inside disposable
|
|
321
334
|
fixtures. The job uses Python argv/bytes so a surrounding shell cannot
|
|
@@ -325,7 +338,7 @@ order of value:
|
|
|
325
338
|
broader UNC/device paths and full-suite portability still require
|
|
326
339
|
separate evidence. A focused Core runner is not a universal Windows E2E
|
|
327
340
|
claim.
|
|
328
|
-
- `0.2.3-rc2`
|
|
341
|
+
- Offline `guard-lab` MVP, introduced in `0.2.3-rc2` and shipped in `0.2.3`: disposable
|
|
329
342
|
synthetic fixtures, zero-token controls, a bounded loopback observer,
|
|
330
343
|
explicit-output marker scanning, chained evidence, and fail-inconclusive
|
|
331
344
|
reports. General file-read visibility, remote callbacks, real-model rating,
|
|
@@ -335,4 +348,5 @@ order of value:
|
|
|
335
348
|
- V3+: `database-guard` (compensations = transaction / backup /
|
|
336
349
|
point-in-time recovery), `cloud-guard` (snapshot / state capture). The
|
|
337
350
|
Guard answers "may this happen"; the Compensation Engine answers "how do
|
|
338
|
-
we come back"
|
|
351
|
+
we come back". These remain design directions requiring separate scope and
|
|
352
|
+
implementation decisions.
|
|
@@ -74,6 +74,44 @@ must accept the additional refusal reason and ignore unknown optional fields.
|
|
|
74
74
|
| `doctor.py --live-sentinel` and hashed hook receipt | minor | Explicit, opt-in real-host/model probe only. Default doctor behavior is unchanged; raw command/model output is not retained, and incomplete evidence is `INCONCLUSIVE` rather than PASS |
|
|
75
75
|
| Cross-vocabulary mismatch floor (`0.2.3-rc1`) | minor safety fix | At a selected-dialect command boundary, a supported destructive shape that produced no operation becomes target-free `UNKNOWN` → `BLOCK_UNDETERMINABLE_EFFECT`; it never borrows a compensation plan from another grammar |
|
|
76
76
|
|
|
77
|
+
### 0.2.5-rc1 assessment contract clarification (source candidate)
|
|
78
|
+
|
|
79
|
+
Advisory and dry-run retain their existing best-effort audit behavior and
|
|
80
|
+
metadata side effects. Tests and documentation distinguish unchanged command
|
|
81
|
+
targets from zero filesystem writes, and advisory exit 0 from execution
|
|
82
|
+
authorization. No flag, result field, policy decision, audit storage location
|
|
83
|
+
or exit code changes. See the [assessment contract](../../skills/delete-guard/references/policy.md#assessment-and-dry-run-side-effects).
|
|
84
|
+
|
|
85
|
+
### 0.2.5-rc1 safe_delete audit minimization (source candidate)
|
|
86
|
+
|
|
87
|
+
New safe_delete audit events replace raw target/reason payloads with
|
|
88
|
+
`target_count`; established relocation reports retain `txid` and add
|
|
89
|
+
`moved_count`/`skipped_count`, including storage-failure decisions. Decision
|
|
90
|
+
codes, phases and static outcome labels remain available. Free-form
|
|
91
|
+
`--reason` stays accepted but is omitted from new audit events and
|
|
92
|
+
`tx-start.meta`. Essential recovery paths/intents, CLI result fields,
|
|
93
|
+
verdicts, exit codes and durability gates retain their behavior.
|
|
94
|
+
Audit event shapes are not frozen. Historical records are not rewritten,
|
|
95
|
+
and generic audit writers, automatic session identity and other output
|
|
96
|
+
surfaces are unchanged. See the [writer contract](../../skills/delete-guard/references/policy.md#safe_delete-audit-metadata).
|
|
97
|
+
|
|
98
|
+
### 0.2.5-rc1 exemption configuration diagnostics (source candidate)
|
|
99
|
+
|
|
100
|
+
The existing limited parser, first-readable-file precedence and exemption
|
|
101
|
+
matching are retained. No full TOML/gitignore parser, configuration migration,
|
|
102
|
+
production dependency or new policy reason is added. Unknown top-level keys
|
|
103
|
+
and bare lines remain ineffective; recognized legacy entries may still apply
|
|
104
|
+
alongside warnings. Diagnostics do not change verdicts or exit codes.
|
|
105
|
+
|
|
106
|
+
Successful text scans may add `exemption` provenance/count/diagnostic metadata
|
|
107
|
+
to checker JSON and the sanitizer library result. Human checker and sanitizer
|
|
108
|
+
CLI warnings use stderr; JSON checker stdout and sanitizer payload/plan stdout
|
|
109
|
+
keep their respective formats. Normal missing/valid configurations remain
|
|
110
|
+
quiet. Diagnostic codes are configuration metadata, not Decision Protocol
|
|
111
|
+
reason codes. Consumers should tolerate the additive fields and warnings;
|
|
112
|
+
the manifest is 0.2.5-rc1, selected as a prerelease candidate. The diagnostic
|
|
113
|
+
grammar and privacy contract are in [rules.md](../../skills/exfil-guard/references/rules.md#configuration-diagnostics).
|
|
114
|
+
|
|
77
115
|
### 0.2.0 check output minimization
|
|
78
116
|
|
|
79
117
|
`check.py` still returns the same decision class, reason code, static
|
|
@@ -161,9 +199,40 @@ Every expansion is recorded in the op notes for audit.
|
|
|
161
199
|
|
|
162
200
|
## Verdict changes since v0.1.1
|
|
163
201
|
|
|
202
|
+
### 0.2.5-rc1 lifecycle and restore-audit maintenance (source candidate)
|
|
203
|
+
|
|
204
|
+
Existing `BLOCK_PROTECTED_PATH` now wins before `ALLOW_TRASH_GC` for
|
|
205
|
+
workspace/Git and quarantine control paths. Quarantine root metadata,
|
|
206
|
+
session state and in-workspace storage parents are protected. Ordinary
|
|
207
|
+
unprotected explicit payload housekeeping and the explicit GC CLI remain
|
|
208
|
+
available. Opaque quarantine globs now return `BLOCK_WILDCARD`; safe_delete
|
|
209
|
+
can enumerate a concrete batch before policy checks.
|
|
210
|
+
See [F26](../history/friction.md#f26--housekeeping-overrode-quarantine-control-protection).
|
|
211
|
+
This changes default verdicts and would ordinarily follow the minor-release
|
|
212
|
+
contract. The maintainer explicitly selected 0.2.5-rc1 for this maintenance
|
|
213
|
+
candidate instead of 0.3.0. This is a new, bounded exception for the existing
|
|
214
|
+
control-path/glob, PURGED inventory, audit-writer and exemption-diagnostic
|
|
215
|
+
maintenance, not an extension of the prior 0.2.4 exception to arbitrary changes.
|
|
216
|
+
Existing decision/reason strings, CLI arguments and exit codes retain their
|
|
217
|
+
roles. There is no manifest migration or production dependency. Publication,
|
|
218
|
+
and any later stable 0.2.5 decision, remain separate from candidate preparation.
|
|
219
|
+
The exact -rcN tag maps to GitHub prerelease and npm rc, preserving stable latest.
|
|
220
|
+
See the [candidate notes](../releases/release-notes-0.2.5-rc1.md).
|
|
221
|
+
|
|
222
|
+
Active `tx_inventory` and GC plans now omit `PURGED` history, while
|
|
223
|
+
`transactions` and manifests retain it. Failed/unpurged transactions retain
|
|
224
|
+
their prior eligibility rules; no stash deletion or storage migration is added.
|
|
225
|
+
|
|
226
|
+
Restore audit records replace `restored`/`conflicts`/`errors` payload copies
|
|
227
|
+
with `restored_count`/`conflict_count`/`error_count`. Established IDs and backup
|
|
228
|
+
attempt IDs stay correlated; invalid/unknown caller IDs use `txid_sha256`.
|
|
229
|
+
Audit shapes beyond manifests are not frozen. CLI parameters, exit codes,
|
|
230
|
+
recovery manifests and returned recovery paths/errors retain their roles.
|
|
231
|
+
This is one writer's minimization, not general recursive audit sanitization.
|
|
232
|
+
|
|
164
233
|
A changed default verdict for an existing shape is a **minor** release and
|
|
165
234
|
requires an entry in [friction.md](../history/friction.md) - never a silent behaviour
|
|
166
|
-
shift. The
|
|
235
|
+
shift. The bounded 0.2.4 and 0.2.5-rc1 exceptions are recorded above. Additive reason codes
|
|
167
236
|
are listed above; this table is for shapes
|
|
168
237
|
whose *existing* verdict moved.
|
|
169
238
|
|
|
@@ -175,6 +244,7 @@ whose *existing* verdict moved.
|
|
|
175
244
|
| Attached or newline-separated destructive commands (`echo ok;rm ...`, `echo ok` followed by newline and `rm ...`) | Could miss the destructive segment | Classifies and applies its normal policy | POSIX command boundaries must be preserved by the lexer |
|
|
176
245
|
| `git reset --hard [ref]` with untracked/ignored or quarantine collisions | Tracked-only `SNAPSHOT` could proceed | `BLOCK` / `BLOCK_GIT_RESET_COLLISION` | Stash does not preserve the colliding content (0.2.4 maintenance exception, F24) |
|
|
177
246
|
| Hard reset with uncertain preflight or unsupported compound/wrapper context | Could proceed or ask despite incomplete coverage | `BLOCK_UNDETERMINABLE_EFFECT` before compensation | Snapshot and preflight must describe the actual Git context (F24) |
|
|
247
|
+
| Quarantine root/control paths, protected metadata inside trash, or an in-workspace storage parent | Could be allowed as housekeeping or regenerable content | `BLOCK_PROTECTED_PATH` | Recovery/state evidence protection precedes housekeeping (0.2.5-rc1 candidate, F26) |
|
|
178
248
|
|
|
179
249
|
Unchanged on purpose: a genuine compensation fault (`git stash create`
|
|
180
250
|
failing, a relocation that does not cover every target, an audit intent
|