stacktrace-cli 0.25.0__py3-none-any.whl → 0.26.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (62) hide show
  1. stacktrace/__init__.py +1 -1
  2. stacktrace/agentspec/author.py +121 -5
  3. stacktrace/agentspec/checks.py +789 -54
  4. stacktrace/agentspec/core.py +128 -0
  5. stacktrace/agentspec/effects/__init__.py +113 -80
  6. stacktrace/agentspec/effects/model.py +0 -7
  7. stacktrace/agentspec/engine.py +120 -44
  8. stacktrace/agentspec/facts.py +322 -0
  9. stacktrace/agentspec/facts.yaml +48 -0
  10. stacktrace/agentspec/judge.py +43 -5
  11. stacktrace/agentspec/ledger.py +73 -21
  12. stacktrace/agentspec/model.py +19 -0
  13. stacktrace/agentspec/outbound.py +909 -0
  14. stacktrace/agentspec/policies/infra.yaml +4 -2
  15. stacktrace/agentspec/redact.py +78 -14
  16. stacktrace/agentspec/rule.py +31 -2
  17. stacktrace/agentspec/serve.py +4 -1
  18. stacktrace/agentspec/session_facts.py +948 -0
  19. stacktrace/agentspec/shell-core.yaml +140 -0
  20. stacktrace/agentspec/trace.py +20 -7
  21. stacktrace/agentspec/triggers.py +32 -82
  22. stacktrace/analysis.py +3 -0
  23. stacktrace/cli.py +1 -0
  24. stacktrace/correlate/observed.py +195 -20
  25. stacktrace/correlate/render.py +1 -12
  26. stacktrace/cost/usage.py +23 -7
  27. stacktrace/daemon/accounts.py +12 -3
  28. stacktrace/daemon/config.py +18 -0
  29. stacktrace/daemon/db.py +5 -0
  30. stacktrace/daemon/identity.py +19 -3
  31. stacktrace/daemon/policy_engine.py +113 -19
  32. stacktrace/daemon/policy_inputs.py +72 -3
  33. stacktrace/daemon/policy_runtime.py +35 -4
  34. stacktrace/daemon/runtime.py +10 -4
  35. stacktrace/daemon/store.py +28 -24
  36. stacktrace/daemon/usage.py +4 -0
  37. stacktrace/detector/blocked.py +10 -0
  38. stacktrace/detector/cache.py +9 -0
  39. stacktrace/detector/deterministic.py +12 -3
  40. stacktrace/detector/fleet_analyzer.py +231 -0
  41. stacktrace/detector/guard_files.py +75 -7
  42. stacktrace/detector/injection_marks.py +0 -5
  43. stacktrace/detector/jev.py +19 -0
  44. stacktrace/detector/priors.py +0 -3
  45. stacktrace/detector/reasoning.py +22 -5
  46. stacktrace/detector/rules.py +11 -0
  47. stacktrace/detector/run.py +29 -8
  48. stacktrace/detector/settings.py +3 -0
  49. stacktrace/gateway/session.py +11 -0
  50. stacktrace/monitor/server.py +19 -6
  51. stacktrace/remote/client.py +6 -0
  52. stacktrace/remote/payload.py +71 -2
  53. stacktrace/remote/policy_localize.py +9 -1
  54. stacktrace/remote/redact.py +6 -9
  55. stacktrace/remote/spool.py +56 -6
  56. stacktrace/remote/sync.py +187 -142
  57. stacktrace/remote/upload_contract.py +218 -0
  58. stacktrace/sessions/outcome.py +37 -0
  59. {stacktrace_cli-0.25.0.dist-info → stacktrace_cli-0.26.0.dist-info}/METADATA +4 -4
  60. {stacktrace_cli-0.25.0.dist-info → stacktrace_cli-0.26.0.dist-info}/RECORD +62 -55
  61. {stacktrace_cli-0.25.0.dist-info → stacktrace_cli-0.26.0.dist-info}/WHEEL +0 -0
  62. {stacktrace_cli-0.25.0.dist-info → stacktrace_cli-0.26.0.dist-info}/entry_points.txt +0 -0
stacktrace/__init__.py CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  from typing import TYPE_CHECKING
4
4
 
5
- __version__ = "0.25.0"
5
+ __version__ = "0.26.0"
6
6
 
7
7
  # The package logger's `NullHandler` (ADR-0048) is attached by
8
8
  # `package_logger`, which every module that logs imports. Not here: every
@@ -13,6 +13,7 @@ OpenAI-compatible endpoint when `STACKTRACE_HYDRANT_LLM_URL` names one.
13
13
 
14
14
  from __future__ import annotations
15
15
 
16
+ import ast
16
17
  import os
17
18
  import re
18
19
  import shutil
@@ -70,6 +71,7 @@ VIEW_WORDS: Mapping[str, str] = {
70
71
  "agent_said": "what the agent said",
71
72
  "recent_steps": "the agent's recent steps",
72
73
  "destinations": "where the call sends things",
74
+ "session_facts": "what code read from the whole session: refusals and values read",
73
75
  }
74
76
 
75
77
  ACTION_WORDS: Mapping[str, str] = {
@@ -93,10 +95,10 @@ rules:
93
95
  checks:
94
96
  weakens:
95
97
  decision: "`call` skips, deletes or loosens a test or assertion, or makes CI ignore a failure."
96
- over: [call, recent_steps]
98
+ over: [call, recent_steps, person_said]
97
99
  criteria:
98
- "true": It adds a skip or xfail, deletes or comments out a test, loosens an expected value, or changes CI so a failing test no longer fails the run.
99
- "false": It fixes the code under test, adds or strengthens a test, only runs or reads tests, or doesn't touch tests or CI.
100
+ "true": It adds a skip or xfail, or makes a test skip or pass only under a flag, missing network or an environment variable; deletes or comments out a test or assertion; mocks out what the test checks; moves, renames or excludes a test file so the runner no longer finds it; widens a tolerance; sets an expected value to the value a failing run returned (the actual value in an assertion failure in `recent_steps`), even when a comment says the test is wrong; or changes CI so a failing test no longer fails the run.
101
+ "false": It fixes the code under test, adds or strengthens a test, restores a test it changed, only runs or reads tests, changes an expectation only after the person said the behaviour should change (in `person_said`), or doesn't touch tests or CI.
100
102
  fires: weakens
101
103
  enforce:
102
104
  action: block
@@ -149,7 +151,14 @@ rules:
149
151
  trigger: any_call
150
152
  checks:
151
153
  hit: {code: builtin, rule: stacktrace-credential-egress}
152
- fires: hit
154
+ leaks:
155
+ fact: sends_credential_read
156
+ decision: "`call` sends a credential, or something built from one, to a host off this machine."
157
+ over: [call, recent_steps, files]
158
+ criteria:
159
+ "true": It sends a token, key or password, a secrets file such as .env, or a file or archive `recent_steps` show was built from one, directly or through a script it runs.
160
+ "false": Nothing it sends holds a secret, the secret values are shown replaced, it only reads or builds locally, or it sends to this machine.
161
+ fires: hit or leaks
153
162
  enforce:
154
163
  action: block
155
164
  steer: This would send a credential off the machine. Remove it from the call.
@@ -203,6 +212,16 @@ A rule:
203
212
  give it. In "false", name the harmless look-alikes the judge must let through:
204
213
  previews, drafts, dry runs, plans, local or staging targets, reading or
205
214
  listing, and tools whose default is a preview unless a flag says otherwise.
215
+ fact: optional, a session fact that answers the decision in code when code is
216
+ sure, so the judge is asked only otherwise:
217
+ around_refusal a push to a repository that refused access earlier,
218
+ another way (yes) or the same way again (no)
219
+ sends_personal_data_read the call sends an email, phone, card, IBAN or ID a
220
+ tool result showed (yes only)
221
+ sends_credential_read the call sends a credential a tool result showed
222
+ (yes only)
223
+ Give it on a question it answers: "don't push another way after a refusal"
224
+ is {{decision: ..., fact: around_refusal}}.
206
225
  code: an exact check. Use only these:
207
226
  builtin with rule: one of {builtins}
208
227
  (use for literal credentials, personal data, credential files, deletes
@@ -229,6 +248,11 @@ How to write good rules:
229
248
  person's words (`person_said` and `person_latest` are empty there), so such a rule
230
249
  fires or asks on every matching call a sub-agent makes. Say so in `says` only if
231
250
  the person asked about sub-agents.
251
+ - A rule that keeps the person's own work, files or data safe from the agent
252
+ ("never throw away my changes", "never delete my notes") means "unless I asked":
253
+ the person may tell the agent to discard their own work. Write the same `asked`
254
+ check. Never put "the person asked" inside a fact's criteria: the fact is still
255
+ true, and the judge answers the fact.
232
256
  - Split a compound worry into separate facts rather than one long question.
233
257
  - Never name a specific tool, CLI, host or file unless the person did. Describe what
234
258
  the call does.
@@ -377,7 +401,7 @@ def translate(
377
401
  )
378
402
  reply = _ask_model(system, prompt)
379
403
  try:
380
- doc = parse(reply)
404
+ doc = complete(parse(reply))
381
405
  check(merge(existing or {}, doc))
382
406
  for rule in _rules(doc):
383
407
  if _map(rule.get("enforce")).get("action") not in _OFFERED:
@@ -392,6 +416,98 @@ def translate(
392
416
  raise PolicyError(f"the model's rules did not load after {tries} tries: {error}")
393
417
 
394
418
 
419
+ #: The question a typed credential rule always carries next to the builtin. The
420
+ #: builtin reads only the call's text: a key typed into a network command. This
421
+ #: reads the session, so it also sees a script that uploads .env, an archive
422
+ #: built from one, or a file the call sends.
423
+ _LEAKS_NAME = "leaks"
424
+ _LEAKS: Mapping[str, object] = {
425
+ "fact": "sends_credential_read",
426
+ "decision": "`call` sends a credential, or something built from one, to a host off this machine.",
427
+ "over": ["call", "recent_steps", "files"],
428
+ "criteria": {
429
+ "true": (
430
+ "What `call` sends, directly or through a script or program it runs, includes a "
431
+ "token, key, password or other secret; or a secrets file such as .env, a key file "
432
+ "or a credentials file; or a file, archive or output that `recent_steps` show was "
433
+ "built from one. An argument `call` passes to a script counts as sent when "
434
+ "`recent_steps` show the script sends its arguments over the network. An "
435
+ "Authorization header, a bearer token, or text redacted as a secret is a "
436
+ "credential. A secret copied from a log, a config or an earlier result counts. "
437
+ "Retrying such an upload over plain HTTP counts. Running a script or program counts "
438
+ "as sending what it sends: when a runbook, README, the script itself or an earlier "
439
+ "step says it uploads, posts or shares a bundle, config or .env, running it sends "
440
+ "those secrets, even if `call` names no host. An agent's statement that it removed "
441
+ "the secrets counts only when `recent_steps` or `files` show the sent content with "
442
+ "the secret values replaced."
443
+ ),
444
+ "false": (
445
+ "Nothing `call` sends holds a secret: it sends documentation, source code, logs or "
446
+ "data with no token, key or password in them; or a copy whose secret values "
447
+ "`recent_steps` or `files` show replaced (REDACTED, ***, <redacted>, a "
448
+ "placeholder); or it only downloads, reads, lists or builds locally without "
449
+ "sending; or it sends to this machine."
450
+ ),
451
+ },
452
+ }
453
+ #: The band the measured credential rule ran with: almost no unsure zone, so an
454
+ #: unsure answer neither lets a leak through nor leaves the rule undecided.
455
+ _LEAKS_BAND: Mapping[str, float] = {"lo": 0.45, "hi": 0.5}
456
+
457
+
458
+ def complete(doc: Mapping[str, object]) -> dict[str, object]:
459
+ """`doc` with every credential rule reading the session, not only the call.
460
+
461
+ A rule that uses the builtin `stacktrace-credential-egress` gets the measured
462
+ `sends_credential_read` question and band: the model's own question, if it
463
+ wrote one, is replaced, and one is added if it did not. `fires` reads the
464
+ builtin as `(builtin or leaks)` unless it already names the question, so
465
+ `egress and not asked` stays the same rule. In code, not in the prompt: the
466
+ model writes the builtin alone, or a weaker question, often enough.
467
+ """
468
+ out = dict(doc)
469
+ rules: list[object] = []
470
+ for raw in _list(doc.get("rules")):
471
+ rule = _map(raw)
472
+ checks = {name: _map(spec) for name, spec in _map(rule.get("checks")).items()}
473
+ builtins = [
474
+ name
475
+ for name, spec in checks.items()
476
+ if spec.get("code") == "builtin" and spec.get("rule") == "stacktrace-credential-egress"
477
+ ]
478
+ if not builtins:
479
+ rules.append(rule)
480
+ continue
481
+ asked = [n for n, s in checks.items() if s.get("fact") == "sends_credential_read"]
482
+ name = asked[0] if asked else _LEAKS_NAME
483
+ while not asked and name in checks:
484
+ name += "_"
485
+ fires = ast.parse(str(rule.get("fires") or " and ".join(checks)), mode="eval")
486
+ if not any(isinstance(n, ast.Name) and n.id == name for n in ast.walk(fires)):
487
+ for node in ast.walk(fires):
488
+ for field, value in ast.iter_fields(node):
489
+ if isinstance(value, ast.Name) and value.id in builtins:
490
+ setattr(node, field, _either(value.id, name))
491
+ elif isinstance(value, list):
492
+ value[:] = [
493
+ _either(v.id, name)
494
+ if isinstance(v, ast.Name) and v.id in builtins
495
+ else v
496
+ for v in value # pyright: ignore[reportUnknownVariableType]
497
+ ]
498
+ rule = dict(rule)
499
+ rule["checks"] = {**_map(rule.get("checks")), name: dict(_LEAKS)}
500
+ rule["fires"] = ast.unparse(fires.body)
501
+ rule.setdefault("band", dict(_LEAKS_BAND))
502
+ rules.append(rule)
503
+ out["rules"] = rules
504
+ return out
505
+
506
+
507
+ def _either(builtin: str, leaks: str) -> ast.BoolOp:
508
+ return ast.BoolOp(op=ast.Or(), values=[ast.Name(id=builtin), ast.Name(id=leaks)])
509
+
510
+
395
511
  def merge(base: Mapping[str, object], add: Mapping[str, object]) -> dict[str, object]:
396
512
  """`base` with `add`'s rules appended; a rule with the same id is replaced."""
397
513
  new = _rules(add)