@mokuyoaxis/agent-guard 0.2.4 → 0.2.5-rc2
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 +166 -573
- package/README.zh-CN.md +138 -489
- 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/audit.py +170 -25
- package/core/classifier.py +25 -1
- package/core/lab.py +77 -7
- package/core/policy.py +17 -9
- package/core/recovery.py +5 -1
- package/core/redaction.py +122 -21
- package/docs/README.md +18 -5
- package/docs/design/architecture.md +25 -6
- package/docs/design/compatibility.md +106 -1
- package/docs/design/threat-model.md +6 -4
- package/docs/guides/audit-metadata.md +77 -0
- package/docs/guides/getting-started.md +106 -0
- package/docs/guides/harness-capabilities.md +5 -0
- package/docs/history/friction.md +85 -0
- package/docs/lab/guard-lab.md +15 -1
- package/docs/releases/release-notes-0.2.5-rc1.md +91 -0
- package/docs/releases/release-notes-0.2.5-rc2.md +101 -0
- package/guard_lab.py +11 -0
- package/package.json +4 -2
- package/skills/delete-guard/SKILL.md +45 -7
- package/skills/delete-guard/references/policy.md +90 -4
- package/skills/delete-guard/scripts/check.py +3 -0
- package/skills/delete-guard/scripts/gc.py +18 -3
- package/skills/delete-guard/scripts/restore.py +22 -7
- package/skills/delete-guard/scripts/safe_delete.py +52 -29
- package/skills/delete-guard/scripts/status.py +9 -7
- package/skills/exfil-guard/SKILL.md +23 -11
- package/skills/exfil-guard/references/channels.md +8 -1
- package/skills/exfil-guard/references/rules.md +86 -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/audit.py
CHANGED
|
@@ -1,22 +1,167 @@
|
|
|
1
1
|
"""Auditability pillar: append-only JSONL evidence log.
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
3
|
+
Records contain supported metadata, not arbitrary caller payloads. Reading
|
|
4
|
+
legacy records applies the same projection without rewriting the log.
|
|
5
|
+
Durability and append-only storage remain separate from recovery manifests,
|
|
6
|
+
which retain the exact paths required to restore data.
|
|
7
7
|
"""
|
|
8
8
|
from __future__ import annotations
|
|
9
9
|
|
|
10
|
-
import
|
|
10
|
+
from collections import deque
|
|
11
|
+
from functools import lru_cache
|
|
12
|
+
import hashlib
|
|
11
13
|
import json
|
|
14
|
+
import math
|
|
12
15
|
import os
|
|
13
|
-
import
|
|
16
|
+
import re
|
|
14
17
|
import threading
|
|
15
18
|
import time
|
|
16
19
|
import uuid
|
|
17
|
-
from typing import Any, Dict, List
|
|
20
|
+
from typing import Any, Dict, List
|
|
18
21
|
|
|
19
22
|
_APPEND_LOCK = threading.Lock()
|
|
23
|
+
_LOCAL_SESSION = uuid.uuid4().hex
|
|
24
|
+
_CORRELATION_RE = re.compile(r"sha256:[0-9a-f]{64}\Z")
|
|
25
|
+
_TXID_RE = re.compile(r"[0-9]{8}-[0-9]{6}-[0-9a-f]{8}\Z")
|
|
26
|
+
_TIMESTAMP_RE = re.compile(r"[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z\Z")
|
|
27
|
+
_HASH_RE = re.compile(r"[0-9a-f]{64}\Z")
|
|
28
|
+
_GIT_SHA_RE = re.compile(r"[0-9a-f]{40}(?:[0-9a-f]{24})?\Z")
|
|
29
|
+
_COUNTS = frozenset({
|
|
30
|
+
"target_count", "moved_count", "skipped_count", "restored_count",
|
|
31
|
+
"conflict_count", "error_count", "missing_count", "moved", "skipped",
|
|
32
|
+
"enumerated", "start", "end", "length",
|
|
33
|
+
})
|
|
34
|
+
_IDENTIFIERS = frozenset({"txid", "check_id", "plan_id"})
|
|
35
|
+
_ID_LISTS = frozenset({"txids", "backup_txids", "purged", "missing"})
|
|
36
|
+
_COMPENSATION_FIELDS = frozenset({
|
|
37
|
+
"strategy", "txid", "status", "moved", "skipped", "enumerated", "sha",
|
|
38
|
+
})
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def correlation_id(value: str) -> str:
|
|
42
|
+
"""Opaque, deterministic correlation; not encryption or authentication.
|
|
43
|
+
|
|
44
|
+
Already-projected identifiers remain stable when read or re-appended.
|
|
45
|
+
Surrogate escapes in POSIX metadata are hashed without emitting them.
|
|
46
|
+
"""
|
|
47
|
+
if _CORRELATION_RE.fullmatch(value):
|
|
48
|
+
return value
|
|
49
|
+
return "sha256:" + hashlib.sha256(
|
|
50
|
+
value.encode("utf-8", errors="surrogatepass")).hexdigest()
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
def _identifier(value: str) -> str:
|
|
54
|
+
# Generated recovery/check IDs stay directly usable. Other spellings
|
|
55
|
+
# retain correlation without becoming an arbitrary text channel.
|
|
56
|
+
return value if _TXID_RE.fullmatch(value) else correlation_id(value)
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
@lru_cache(maxsize=1)
|
|
60
|
+
def _enums():
|
|
61
|
+
# Import after module initialization: recovery imports the ID/time
|
|
62
|
+
# helpers above, and needs no policy or redaction decisions here.
|
|
63
|
+
from . import dialects, policy, redaction
|
|
64
|
+
decisions = frozenset({"ALLOW", "RELOCATE", "SNAPSHOT", "SANITIZE", "ASK", "BLOCK"})
|
|
65
|
+
return {
|
|
66
|
+
"event": frozenset({
|
|
67
|
+
"check", "ask", "decision", "advisory", "intent", "outcome",
|
|
68
|
+
"enforce-block", "enforce-intent", "enforce-error", "enforce-proceed",
|
|
69
|
+
"restore", "gc-intent", "gc",
|
|
70
|
+
}) | {"exfil-" + decision.lower() for decision in decisions},
|
|
71
|
+
"decision": decisions, "action": decisions | {"PURGED"},
|
|
72
|
+
"code": frozenset(policy.EXPLANATIONS),
|
|
73
|
+
"tool": frozenset({"safe_delete", "check", "restore", "gc"}),
|
|
74
|
+
"phase": frozenset({"advisory", "intent", "complete"}),
|
|
75
|
+
"outcome": frozenset({
|
|
76
|
+
"relocated to quarantine", "deleted directly (provably regenerable)",
|
|
77
|
+
"deleted directly (quarantine housekeeping)",
|
|
78
|
+
}),
|
|
79
|
+
"dialect": frozenset(dialects.DIALECT_ALIASES.values()),
|
|
80
|
+
"dialect_requested": frozenset(dialects.DIALECT_ALIASES) | {"<redacted>"},
|
|
81
|
+
"dialect_outcome": frozenset({"ok", "unusable"}),
|
|
82
|
+
"strategy": frozenset({"relocate", "clean-enumerate", "snapshot"}),
|
|
83
|
+
"status": frozenset({"started", "complete", "partial", "storage-failed",
|
|
84
|
+
"failed", "incomplete"}),
|
|
85
|
+
"rule_id": frozenset(value for key, value in vars(redaction).items()
|
|
86
|
+
if key.startswith("RULE_") and isinstance(value, str)),
|
|
87
|
+
"family": frozenset({"secret", "path"}),
|
|
88
|
+
"confidence": frozenset({"deterministic", "contextual"}),
|
|
89
|
+
"channel": frozenset(redaction.CHANNELS),
|
|
90
|
+
"context": frozenset({"prose", "key", "uri-userinfo", "env-var"}),
|
|
91
|
+
"command": frozenset({"<redacted>"}),
|
|
92
|
+
"error": frozenset({"compensation failed"}),
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
def project(record: Dict[str, Any]) -> Dict[str, Any]:
|
|
97
|
+
"""Supported metadata only; unknown fields/types/free text are omitted.
|
|
98
|
+
|
|
99
|
+
This is a closed record projection, not a general text sanitizer. Nested
|
|
100
|
+
compensation records and GC reason maps have explicit shapes. Recovery
|
|
101
|
+
journals, authorization state, and caller objects are never modified.
|
|
102
|
+
"""
|
|
103
|
+
if not isinstance(record, dict):
|
|
104
|
+
raise TypeError("audit record must be an object")
|
|
105
|
+
stored: Dict[str, Any] = {}
|
|
106
|
+
for key, allowed in _enums().items():
|
|
107
|
+
value = record.get(key)
|
|
108
|
+
if key == "context" and isinstance(value, str) and value.startswith("key="):
|
|
109
|
+
value = "key"
|
|
110
|
+
if isinstance(value, str) and value in allowed:
|
|
111
|
+
stored[key] = value
|
|
112
|
+
for key in _COUNTS:
|
|
113
|
+
value = record.get(key)
|
|
114
|
+
if type(value) is int and value >= 0:
|
|
115
|
+
stored[key] = value
|
|
116
|
+
for key in ("force", "ok", "exempted"):
|
|
117
|
+
if type(record.get(key)) is bool:
|
|
118
|
+
stored[key] = record[key]
|
|
119
|
+
latency = record.get("guard_latency_ms")
|
|
120
|
+
if (type(latency) is int and latency >= 0 or
|
|
121
|
+
type(latency) is float and math.isfinite(latency) and latency >= 0):
|
|
122
|
+
stored["guard_latency_ms"] = latency
|
|
123
|
+
ts = record.get("ts")
|
|
124
|
+
if isinstance(ts, str) and _TIMESTAMP_RE.fullmatch(ts):
|
|
125
|
+
stored["ts"] = ts
|
|
126
|
+
for key in _IDENTIFIERS:
|
|
127
|
+
value = record.get(key)
|
|
128
|
+
if isinstance(value, str) and value:
|
|
129
|
+
stored[key] = _identifier(value)
|
|
130
|
+
for key in _ID_LISTS:
|
|
131
|
+
values = record.get(key)
|
|
132
|
+
if isinstance(values, list):
|
|
133
|
+
stored[key] = [_identifier(v) for v in values if isinstance(v, str) and v]
|
|
134
|
+
session = record.get("session")
|
|
135
|
+
if isinstance(session, str) and session:
|
|
136
|
+
stored["session"] = correlation_id(session)
|
|
137
|
+
digest = record.get("txid_sha256")
|
|
138
|
+
if isinstance(digest, str) and _HASH_RE.fullmatch(digest):
|
|
139
|
+
stored["txid_sha256"] = digest
|
|
140
|
+
digests = record.get("missing_txid_sha256")
|
|
141
|
+
if isinstance(digests, list):
|
|
142
|
+
stored["missing_txid_sha256"] = [
|
|
143
|
+
v for v in digests if isinstance(v, str) and _HASH_RE.fullmatch(v)]
|
|
144
|
+
sha = record.get("sha")
|
|
145
|
+
if "sha" in record and (sha is None or isinstance(sha, str) and _GIT_SHA_RE.fullmatch(sha)):
|
|
146
|
+
stored["sha"] = sha
|
|
147
|
+
span = record.get("span")
|
|
148
|
+
if (isinstance(span, list) and len(span) == 2 and
|
|
149
|
+
all(type(v) is int and v >= 0 for v in span) and span[1] >= span[0]):
|
|
150
|
+
stored["span"] = list(span)
|
|
151
|
+
if record.get("reasons") == []:
|
|
152
|
+
stored["reasons"] = []
|
|
153
|
+
compensations = record.get("compensations")
|
|
154
|
+
if isinstance(compensations, list):
|
|
155
|
+
stored["compensations"] = [
|
|
156
|
+
project({k: v for k, v in item.items() if k in _COMPENSATION_FIELDS})
|
|
157
|
+
for item in compensations if isinstance(item, dict)]
|
|
158
|
+
reasons = record.get("plan_reasons")
|
|
159
|
+
if isinstance(reasons, dict):
|
|
160
|
+
stored["plan_reasons"] = {
|
|
161
|
+
_identifier(txid): reason for txid, reason in reasons.items()
|
|
162
|
+
if isinstance(txid, str) and txid and isinstance(reason, str)
|
|
163
|
+
and reason in {"age", "capacity"}}
|
|
164
|
+
return stored
|
|
20
165
|
|
|
21
166
|
|
|
22
167
|
def utc_now_iso() -> str:
|
|
@@ -29,27 +174,20 @@ def new_txid() -> str:
|
|
|
29
174
|
|
|
30
175
|
|
|
31
176
|
def session_id() -> str:
|
|
32
|
-
"""
|
|
177
|
+
"""Opaque correlation for the acting session.
|
|
33
178
|
|
|
34
179
|
An agent harness may identify itself through AGENT_GUARD_SESSION.
|
|
35
180
|
This is correlation metadata, not authentication.
|
|
36
181
|
"""
|
|
37
182
|
env = os.environ.get("AGENT_GUARD_SESSION")
|
|
38
183
|
if env:
|
|
39
|
-
return env
|
|
40
|
-
|
|
41
|
-
user = getpass.getuser()
|
|
42
|
-
except Exception: # pragma: no cover - exotic passwd setups
|
|
43
|
-
user = "unknown"
|
|
44
|
-
# platform.node() is the cross-platform form of os.uname().nodename
|
|
45
|
-
# (os.uname does not exist on Windows); empty on exotic setups.
|
|
46
|
-
host = platform.node() or "localhost"
|
|
47
|
-
return f"{user}@{host}:{os.getpid()}"
|
|
184
|
+
return correlation_id(env)
|
|
185
|
+
return correlation_id(f"{_LOCAL_SESSION}:{os.getpid()}")
|
|
48
186
|
|
|
49
187
|
|
|
50
188
|
def append(record: Dict[str, Any], audit_path: str) -> Dict[str, Any]:
|
|
51
|
-
"""Append
|
|
52
|
-
stored =
|
|
189
|
+
"""Append projected metadata; return exactly what was stored."""
|
|
190
|
+
stored = project(record)
|
|
53
191
|
stored.setdefault("ts", utc_now_iso())
|
|
54
192
|
stored.setdefault("session", session_id())
|
|
55
193
|
line = json.dumps(stored, ensure_ascii=False, sort_keys=True)
|
|
@@ -65,22 +203,29 @@ def append(record: Dict[str, Any], audit_path: str) -> Dict[str, Any]:
|
|
|
65
203
|
|
|
66
204
|
|
|
67
205
|
def tail(audit_path: str, n: int = 20) -> List[Dict[str, Any]]:
|
|
68
|
-
"""
|
|
69
|
-
|
|
206
|
+
"""Last n projected objects; malformed/non-object lines are skipped.
|
|
207
|
+
|
|
208
|
+
A non-positive limit reads nothing. Old bytes are never rewritten.
|
|
209
|
+
"""
|
|
210
|
+
if n <= 0 or not os.path.exists(audit_path):
|
|
70
211
|
return []
|
|
71
|
-
records
|
|
212
|
+
records = deque(maxlen=n)
|
|
72
213
|
with open(audit_path, "r", encoding="utf-8") as fh:
|
|
73
214
|
for raw in fh:
|
|
74
215
|
raw = raw.strip()
|
|
75
216
|
if not raw:
|
|
76
217
|
continue
|
|
77
218
|
try:
|
|
78
|
-
|
|
219
|
+
record = json.loads(raw)
|
|
79
220
|
except json.JSONDecodeError:
|
|
80
221
|
continue
|
|
81
|
-
|
|
222
|
+
if isinstance(record, dict):
|
|
223
|
+
records.append(project(record))
|
|
224
|
+
return list(records)
|
|
82
225
|
|
|
83
226
|
|
|
84
227
|
def find_by_txid(audit_path: str, txid: str) -> List[Dict[str, Any]]:
|
|
85
228
|
"""All audit records belonging to one compensation transaction."""
|
|
86
|
-
|
|
229
|
+
key = _identifier(txid)
|
|
230
|
+
return [r for r in tail(audit_path, n=100_000)
|
|
231
|
+
if r.get("txid") == key]
|
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/lab.py
CHANGED
|
@@ -19,6 +19,7 @@ from pathlib import Path
|
|
|
19
19
|
import re
|
|
20
20
|
import secrets
|
|
21
21
|
from socketserver import TCPServer
|
|
22
|
+
import stat
|
|
22
23
|
import subprocess
|
|
23
24
|
import sys
|
|
24
25
|
import tarfile
|
|
@@ -194,6 +195,10 @@ class LabError(RuntimeError):
|
|
|
194
195
|
"""Expected guard-lab error with a safe, bounded message."""
|
|
195
196
|
|
|
196
197
|
|
|
198
|
+
class _ObserverStartupCancelled(LabError):
|
|
199
|
+
"""The controller stopped this observer before accepting its readiness."""
|
|
200
|
+
|
|
201
|
+
|
|
197
202
|
def _now() -> str:
|
|
198
203
|
return datetime.now(timezone.utc).isoformat()
|
|
199
204
|
|
|
@@ -1026,6 +1031,41 @@ def _write_observer_state(evidence: Path, state: dict[str, Any]) -> None:
|
|
|
1026
1031
|
_atomic_write_json(evidence / "observer.json", state)
|
|
1027
1032
|
|
|
1028
1033
|
|
|
1034
|
+
def _observer_startup_note(stage: str, stream: Any = None) -> None:
|
|
1035
|
+
# Static phases and monotonic time only: never log tokens, paths or errors.
|
|
1036
|
+
try:
|
|
1037
|
+
print(
|
|
1038
|
+
f"observer-startup stage={stage} monotonic={time.monotonic():.6f}",
|
|
1039
|
+
file=sys.stderr if stream is None else stream,
|
|
1040
|
+
flush=True,
|
|
1041
|
+
)
|
|
1042
|
+
except (OSError, ValueError):
|
|
1043
|
+
pass # Diagnosis must not determine the observer's health.
|
|
1044
|
+
|
|
1045
|
+
|
|
1046
|
+
def _observer_arm_note(evidence: Path, stage: str) -> None:
|
|
1047
|
+
flags = os.O_WRONLY | os.O_APPEND | getattr(os, "O_CLOEXEC", 0)
|
|
1048
|
+
flags |= getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0)
|
|
1049
|
+
try:
|
|
1050
|
+
descriptor = os.open(evidence / "observer.log", flags)
|
|
1051
|
+
with os.fdopen(descriptor, "a", encoding="utf-8") as output:
|
|
1052
|
+
if stat.S_ISREG(os.fstat(output.fileno()).st_mode):
|
|
1053
|
+
_observer_startup_note(stage, output)
|
|
1054
|
+
except OSError:
|
|
1055
|
+
pass
|
|
1056
|
+
|
|
1057
|
+
|
|
1058
|
+
def _check_observer_startup_stop(evidence: Path, *, ready: bool = False) -> None:
|
|
1059
|
+
stop_path = evidence / "stop.request"
|
|
1060
|
+
if not stop_path.is_file():
|
|
1061
|
+
return
|
|
1062
|
+
if ready:
|
|
1063
|
+
stop = _read_json(stop_path, "observer stop request")
|
|
1064
|
+
if stop.get("reason") != "OBSERVER_STARTUP_TIMEOUT":
|
|
1065
|
+
return # An ordinary stop after READY keeps its existing meaning.
|
|
1066
|
+
raise _ObserverStartupCancelled("observer startup was cancelled")
|
|
1067
|
+
|
|
1068
|
+
|
|
1029
1069
|
def arm_observer(evidence_dir: Path, duration: int = 60) -> dict[str, Any]:
|
|
1030
1070
|
if duration < MIN_DURATION_SECONDS or duration > MAX_DURATION_SECONDS:
|
|
1031
1071
|
raise LabError("observer duration is outside the supported range")
|
|
@@ -1037,7 +1077,8 @@ def arm_observer(evidence_dir: Path, duration: int = 60) -> dict[str, Any]:
|
|
|
1037
1077
|
raise LabError("observer has already been armed for this run")
|
|
1038
1078
|
|
|
1039
1079
|
log_path = evidence / "observer.log"
|
|
1040
|
-
flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL |
|
|
1080
|
+
flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_APPEND
|
|
1081
|
+
flags |= getattr(os, "O_CLOEXEC", 0)
|
|
1041
1082
|
flags |= getattr(os, "O_NOFOLLOW", 0)
|
|
1042
1083
|
try:
|
|
1043
1084
|
log_descriptor = os.open(log_path, flags, 0o600)
|
|
@@ -1058,7 +1099,8 @@ def arm_observer(evidence_dir: Path, duration: int = 60) -> dict[str, Any]:
|
|
|
1058
1099
|
else:
|
|
1059
1100
|
process_options["start_new_session"] = True
|
|
1060
1101
|
try:
|
|
1061
|
-
with os.fdopen(log_descriptor, "
|
|
1102
|
+
with os.fdopen(log_descriptor, "w", encoding="utf-8") as log_output:
|
|
1103
|
+
_observer_startup_note("SPAWNING", log_output)
|
|
1062
1104
|
process = subprocess.Popen(
|
|
1063
1105
|
[
|
|
1064
1106
|
sys.executable,
|
|
@@ -1077,18 +1119,24 @@ def arm_observer(evidence_dir: Path, duration: int = 60) -> dict[str, Any]:
|
|
|
1077
1119
|
close_fds=True,
|
|
1078
1120
|
**process_options,
|
|
1079
1121
|
)
|
|
1122
|
+
_observer_startup_note("SPAWNED", log_output)
|
|
1080
1123
|
_CHILD_PROCESSES[str(evidence)] = process
|
|
1081
1124
|
except OSError as exc:
|
|
1082
1125
|
raise LabError("observer process could not be started") from exc
|
|
1083
1126
|
|
|
1084
1127
|
deadline = time.monotonic() + 5
|
|
1085
1128
|
last_state: Optional[dict[str, Any]] = None
|
|
1129
|
+
noted_unreadable_state = False
|
|
1086
1130
|
while time.monotonic() < deadline:
|
|
1087
1131
|
try:
|
|
1088
1132
|
last_state = _observer_state(evidence)
|
|
1089
1133
|
except LabError:
|
|
1090
1134
|
last_state = None
|
|
1135
|
+
if not noted_unreadable_state:
|
|
1136
|
+
_observer_arm_note(evidence, "ARM_STATE_UNREADABLE")
|
|
1137
|
+
noted_unreadable_state = True
|
|
1091
1138
|
if last_state and last_state.get("status") == "READY":
|
|
1139
|
+
_observer_arm_note(evidence, "ARM_READY")
|
|
1092
1140
|
return {
|
|
1093
1141
|
"schema_version": SCHEMA_VERSION,
|
|
1094
1142
|
"run_id": run["run_id"],
|
|
@@ -1098,22 +1146,26 @@ def arm_observer(evidence_dir: Path, duration: int = 60) -> dict[str, Any]:
|
|
|
1098
1146
|
"duration_seconds": duration,
|
|
1099
1147
|
}
|
|
1100
1148
|
if last_state and last_state.get("status") == "FAILED":
|
|
1101
|
-
|
|
1102
|
-
|
|
1149
|
+
_observer_arm_note(evidence, "ARM_FAILED")
|
|
1150
|
+
_reap_local_observer(evidence)
|
|
1103
1151
|
raise LabError("observer failed its startup self-check")
|
|
1104
1152
|
if process.poll() is not None:
|
|
1105
1153
|
_CHILD_PROCESSES.pop(str(evidence), None)
|
|
1154
|
+
_observer_arm_note(evidence, "ARM_EXITED")
|
|
1106
1155
|
raise LabError("observer exited before becoming ready")
|
|
1107
1156
|
time.sleep(0.05)
|
|
1157
|
+
_observer_arm_note(evidence, "ARM_TIMEOUT")
|
|
1108
1158
|
stop_path = evidence / "stop.request"
|
|
1109
1159
|
if not stop_path.exists():
|
|
1110
1160
|
try:
|
|
1111
1161
|
_write_new_json(
|
|
1112
1162
|
stop_path,
|
|
1113
|
-
{"schema_version": SCHEMA_VERSION, "requested_at": _now()
|
|
1163
|
+
{"schema_version": SCHEMA_VERSION, "requested_at": _now(),
|
|
1164
|
+
"reason": "OBSERVER_STARTUP_TIMEOUT"},
|
|
1114
1165
|
)
|
|
1115
1166
|
except LabError:
|
|
1116
1167
|
pass
|
|
1168
|
+
_reap_local_observer(evidence)
|
|
1117
1169
|
raise LabError("observer did not become ready in time")
|
|
1118
1170
|
|
|
1119
1171
|
|
|
@@ -2023,6 +2075,7 @@ class _LabRequestHandler(BaseHTTPRequestHandler):
|
|
|
2023
2075
|
|
|
2024
2076
|
|
|
2025
2077
|
def run_observer(evidence_dir: Path, duration: int, supplied_token: str) -> int:
|
|
2078
|
+
_observer_startup_note("VALIDATING")
|
|
2026
2079
|
evidence, run = _load_run(evidence_dir)
|
|
2027
2080
|
control = _load_control(evidence, run)
|
|
2028
2081
|
fixture = _validate_fixture(run, evidence)
|
|
@@ -2030,15 +2083,19 @@ def run_observer(evidence_dir: Path, duration: int, supplied_token: str) -> int:
|
|
|
2030
2083
|
raise LabError("observer control token mismatch")
|
|
2031
2084
|
if _observer_state(evidence) is not None:
|
|
2032
2085
|
raise LabError("observer state already exists")
|
|
2086
|
+
_observer_startup_note("VALIDATED")
|
|
2033
2087
|
|
|
2034
2088
|
started_at = _now()
|
|
2035
2089
|
deadline = time.monotonic() + duration
|
|
2036
2090
|
server: Optional[_LabHTTPServer] = None
|
|
2037
2091
|
try:
|
|
2092
|
+
_check_observer_startup_stop(evidence)
|
|
2093
|
+
_observer_startup_note("BINDING")
|
|
2038
2094
|
server = _LabHTTPServer(
|
|
2039
2095
|
("127.0.0.1", 0), _LabRequestHandler, evidence, run, fixture, control,
|
|
2040
2096
|
str(control["route_token"]),
|
|
2041
2097
|
)
|
|
2098
|
+
_observer_startup_note("BOUND")
|
|
2042
2099
|
server.timeout = 0.25
|
|
2043
2100
|
port = int(server.server_address[1])
|
|
2044
2101
|
endpoint = {
|
|
@@ -2051,6 +2108,9 @@ def run_observer(evidence_dir: Path, duration: int, supplied_token: str) -> int:
|
|
|
2051
2108
|
fixture / "bait" / "url.txt",
|
|
2052
2109
|
f"http://127.0.0.1:{port}/canary/{control['route_token']}\n",
|
|
2053
2110
|
)
|
|
2111
|
+
_observer_startup_note("ENDPOINT_WRITTEN")
|
|
2112
|
+
_check_observer_startup_stop(evidence)
|
|
2113
|
+
_observer_startup_note("PUBLISHING_READY")
|
|
2054
2114
|
_append_event(
|
|
2055
2115
|
evidence,
|
|
2056
2116
|
{
|
|
@@ -2073,9 +2133,12 @@ def run_observer(evidence_dir: Path, duration: int, supplied_token: str) -> int:
|
|
|
2073
2133
|
"duration_seconds": duration,
|
|
2074
2134
|
}
|
|
2075
2135
|
_write_observer_state(evidence, state)
|
|
2136
|
+
_observer_startup_note("READY")
|
|
2137
|
+
_check_observer_startup_stop(evidence, ready=True)
|
|
2076
2138
|
next_heartbeat = time.monotonic() + 0.5
|
|
2077
2139
|
while time.monotonic() < deadline:
|
|
2078
2140
|
if (evidence / "stop.request").is_file():
|
|
2141
|
+
_check_observer_startup_stop(evidence, ready=True)
|
|
2079
2142
|
_append_event(
|
|
2080
2143
|
evidence,
|
|
2081
2144
|
{
|
|
@@ -2113,7 +2176,9 @@ def run_observer(evidence_dir: Path, duration: int, supplied_token: str) -> int:
|
|
|
2113
2176
|
state.update({"status": "EXPIRED", "heartbeat_at": _now(), "stopped_at": _now()})
|
|
2114
2177
|
_write_observer_state(evidence, state)
|
|
2115
2178
|
return 0
|
|
2116
|
-
except Exception:
|
|
2179
|
+
except Exception as exc:
|
|
2180
|
+
cancelled = isinstance(exc, _ObserverStartupCancelled)
|
|
2181
|
+
_observer_startup_note("CANCELLED" if cancelled else "FAILED")
|
|
2117
2182
|
try:
|
|
2118
2183
|
_write_observer_state(
|
|
2119
2184
|
evidence,
|
|
@@ -2124,11 +2189,14 @@ def run_observer(evidence_dir: Path, duration: int, supplied_token: str) -> int:
|
|
|
2124
2189
|
"pid": os.getpid(),
|
|
2125
2190
|
"started_at": started_at,
|
|
2126
2191
|
"heartbeat_at": _now(),
|
|
2127
|
-
"reason": "
|
|
2192
|
+
"reason": ("OBSERVER_STARTUP_CANCELLED" if cancelled
|
|
2193
|
+
else "OBSERVER_RUNTIME_FAILURE"),
|
|
2128
2194
|
},
|
|
2129
2195
|
)
|
|
2130
2196
|
except Exception:
|
|
2131
2197
|
pass
|
|
2198
|
+
if cancelled:
|
|
2199
|
+
return 1
|
|
2132
2200
|
raise
|
|
2133
2201
|
finally:
|
|
2134
2202
|
if server is not None:
|
|
@@ -2391,6 +2459,8 @@ def observer_cli_main(argv: Optional[Sequence[str]] = None) -> int:
|
|
|
2391
2459
|
try:
|
|
2392
2460
|
return run_observer(arguments.evidence_dir, arguments.duration, supplied_token)
|
|
2393
2461
|
except (LabError, OSError, ValueError):
|
|
2462
|
+
_observer_startup_note("FAILED")
|
|
2394
2463
|
return 1
|
|
2395
2464
|
except Exception:
|
|
2465
|
+
_observer_startup_note("FAILED")
|
|
2396
2466
|
return 1
|
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,
|