killchain 0.1.0__tar.gz → 0.1.2__tar.gz

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.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: killchain
3
- Version: 0.1.0
3
+ Version: 0.1.2
4
4
  Summary: Split a build so a frontier coding agent never sees the risky half.
5
5
  Project-URL: Homepage, https://github.com/jcpsimmons/killchain
6
6
  Project-URL: Repository, https://github.com/jcpsimmons/killchain
@@ -226,6 +226,20 @@ private run dir (`private_fixtures.json`), and drive `tests/test_contracts.py`
226
226
  in real mode via `HARNESS_FIXTURES`. Passing there is the integration proof.
227
227
  The harness rejects a public fixture that equals a private one.
228
228
 
229
+ ## Developing
230
+
231
+ ```bash
232
+ uv run --extra dev pytest
233
+ uv run --extra dev ruff check killchain tests
234
+ ```
235
+
236
+ Tests never call a model. The CLI tests pass `--orch-url fake --no-detector`
237
+ and a fake frontier agent, so the whole pipeline runs offline in about two
238
+ seconds. Publishing is gated on them: the workflow runs the suite on Python
239
+ 3.11, 3.12 and 3.13, builds the wheel, then installs that wheel into a clean
240
+ venv and does a partition with it. If the built artifact cannot do a run, it
241
+ does not reach PyPI.
242
+
229
243
  ## Limits
230
244
 
231
245
  Jev predicts refusal; it does not measure it. Refusals are stochastic and
@@ -202,6 +202,20 @@ private run dir (`private_fixtures.json`), and drive `tests/test_contracts.py`
202
202
  in real mode via `HARNESS_FIXTURES`. Passing there is the integration proof.
203
203
  The harness rejects a public fixture that equals a private one.
204
204
 
205
+ ## Developing
206
+
207
+ ```bash
208
+ uv run --extra dev pytest
209
+ uv run --extra dev ruff check killchain tests
210
+ ```
211
+
212
+ Tests never call a model. The CLI tests pass `--orch-url fake --no-detector`
213
+ and a fake frontier agent, so the whole pipeline runs offline in about two
214
+ seconds. Publishing is gated on them: the workflow runs the suite on Python
215
+ 3.11, 3.12 and 3.13, builds the wheel, then installs that wheel into a clean
216
+ venv and does a partition with it. If the built artifact cannot do a run, it
217
+ does not reach PyPI.
218
+
205
219
  ## Limits
206
220
 
207
221
  Jev predicts refusal; it does not measure it. Refusals are stochastic and
@@ -0,0 +1,33 @@
1
+ """killchain: split a build so a frontier agent never sees the risky half.
2
+
3
+ The prompt is partitioned by *refusal risk*, not confidentiality. Anything a
4
+ commercial coding agent would refuse, hedge, simplify, or guess at is routed to
5
+ an abliterated orchestrator model, which then implements it locally. A frontier
6
+ agent (Claude Code, Codex) builds the rest against stubs.
7
+ """
8
+
9
+ def _version() -> str:
10
+ """Read the version from installed metadata.
11
+
12
+ A hardcoded string here drifts from pyproject.toml, and a drifted version
13
+ makes PyPI reject the upload with "file already exists" on every retry.
14
+ Falls back to pyproject.toml when running from an uninstalled source tree,
15
+ and to "0+unknown" if neither is available.
16
+ """
17
+ try:
18
+ from importlib.metadata import version
19
+ return version("killchain")
20
+ except Exception:
21
+ pass
22
+ try:
23
+ import tomllib
24
+ from pathlib import Path
25
+
26
+ pyproject = Path(__file__).resolve().parents[1] / "pyproject.toml"
27
+ return tomllib.loads(pyproject.read_text())["project"]["version"]
28
+ except Exception:
29
+ return "0+unknown"
30
+
31
+
32
+ __version__ = _version()
33
+ __all__ = ["__version__"]
@@ -14,7 +14,7 @@ from __future__ import annotations
14
14
 
15
15
  import json
16
16
  import re
17
- from dataclasses import dataclass, field, asdict
17
+ from dataclasses import asdict, dataclass, field
18
18
  from typing import Any
19
19
 
20
20
  IDENT = re.compile(r"^[a-z_][a-z0-9_]*$")
@@ -118,7 +118,8 @@ class Contract:
118
118
  f"{kind} {n} of {i.module}.{i.function} inputs mismatch params: "
119
119
  f"extra={sorted(extra)} missing={sorted(missing)}")
120
120
  try:
121
- json.dumps(f.inputs); json.dumps(f.output)
121
+ json.dumps(f.inputs)
122
+ json.dumps(f.output)
122
123
  except TypeError as e:
123
124
  raise ContractError(f"{kind} {n} of {i.function} not JSON: {e}")
124
125
  real = {json.dumps([f.inputs, f.output], sort_keys=True) for f in i.private_fixtures}
@@ -18,8 +18,8 @@ from __future__ import annotations
18
18
  import json
19
19
  import os
20
20
  import re
21
- import urllib.request
22
21
  import urllib.error
22
+ import urllib.request
23
23
  from dataclasses import dataclass, field
24
24
 
25
25
  from killchain import routing
@@ -136,7 +136,7 @@ def score_spans(cfg: dict, spans: list[tuple[str, str]],
136
136
  """Score each span against every dimension, then let routing.classify() rule."""
137
137
  if cfg.get("base_url") == "fake":
138
138
  from killchain.fakes import fake_detector
139
- return [_verdict(l, t, s) for (l, t), s in zip(spans, fake_detector(spans))]
139
+ return [_verdict(lbl, txt, sc) for (lbl, txt), sc in zip(spans, fake_detector(spans))]
140
140
  qs = _questions(risky_terms)
141
141
  out: list[RiskVerdict] = []
142
142
  for label, text in spans:
@@ -36,14 +36,14 @@ def run(cfg: dict, prompt: str, public_dir: Path, private_root: Path, log: Path)
36
36
  from killchain.fakes import fake_frontier
37
37
  return fake_frontier(prompt, public_dir)
38
38
  if backend == "claude":
39
- exe = shutil.which("claude") or "claude"
40
- cmd = [exe, "-p", prompt, "--output-format", "text"]
39
+ exe = shutil.which("claude")
40
+ cmd = [exe or "claude", "-p", prompt, "--output-format", "text"]
41
41
  if cfg.get("claude_model"):
42
42
  cmd += ["--model", cfg["claude_model"]]
43
43
  cmd += list(cfg.get("claude_extra_args", []))
44
44
  elif backend == "codex":
45
- exe = shutil.which("codex") or "codex"
46
- cmd = [exe, "exec", "-C", str(public_dir)]
45
+ exe = shutil.which("codex")
46
+ cmd = [exe or "codex", "exec", "-C", str(public_dir)]
47
47
  if cfg.get("codex_model"):
48
48
  cmd += ["-m", cfg["codex_model"]]
49
49
  cmd += list(cfg.get("codex_extra_args", []))
@@ -51,6 +51,12 @@ def run(cfg: dict, prompt: str, public_dir: Path, private_root: Path, log: Path)
51
51
  else:
52
52
  raise FrontierError(f"unknown frontier backend {backend!r}")
53
53
 
54
+ if not exe:
55
+ raise FrontierError(
56
+ f"frontier backend {backend!r} is not installed ({backend} is not on PATH). "
57
+ f"Install it, or pick a different agent with --frontier."
58
+ )
59
+
54
60
  with log.open("w") as lf:
55
61
  lf.write(f"$ {' '.join(cmd[:3])} ... (cwd={public_dir})\n\n")
56
62
  lf.flush()
@@ -42,6 +42,24 @@ def log(msg: str) -> None:
42
42
  print(f"[harness] {msg}", flush=True)
43
43
 
44
44
 
45
+ #: Everything that means "your setup can't run this", as opposed to a harness
46
+ #: bug. These get one readable line and a hint, not a stack trace.
47
+ FAILURES = (
48
+ localmodel.LocalModelError,
49
+ detector.DetectorError,
50
+ frontier.FrontierError,
51
+ ContractError,
52
+ )
53
+
54
+
55
+ def fail(msg: str) -> None:
56
+ """Print a setup failure and exit 1 without a traceback."""
57
+ print(f"\n[harness] cannot continue: {msg}", file=sys.stderr, flush=True)
58
+ print("[harness] run `killchain --doctor` to check config, keys and the frontier agent.",
59
+ file=sys.stderr, flush=True)
60
+ raise SystemExit(1)
61
+
62
+
45
63
  def load_cfg(path: Path, overrides: argparse.Namespace) -> dict:
46
64
  cfg = tomllib.loads(path.read_text())
47
65
  if overrides.frontier:
@@ -64,6 +82,11 @@ def load_cfg(path: Path, overrides: argparse.Namespace) -> dict:
64
82
  # a project); a path = exactly that path.
65
83
  raw_ws = str(cfg["paths"].get("workspace") or "").strip()
66
84
  cfg["paths"]["workspace"] = paths.workspace() if not raw_ws else _abs(raw_ws)
85
+ # Precedence: --private-root, then $KILLCHAIN_PRIVATE_ROOT, then the file.
86
+ # The env var is documented in README and config.toml, so it has to win
87
+ # over the config file's own default or it does nothing.
88
+ if not overrides.private_root and os.environ.get("KILLCHAIN_PRIVATE_ROOT"):
89
+ cfg["paths"]["private_root"] = os.environ["KILLCHAIN_PRIVATE_ROOT"]
67
90
  cfg["paths"]["private_root"] = _abs(cfg["paths"]["private_root"])
68
91
  return cfg
69
92
 
@@ -101,18 +124,30 @@ def partition(cfg: dict, user_prompt: str, denylist, priv: Path) -> Contract:
101
124
  {"role": "user", "content": user_prompt}]
102
125
  tries = int(cfg["orchestrator"].get("max_partition_tries", 4))
103
126
  max_probes = int(det.get("max_probe_rounds", 3))
104
- attempt = probes = 0
105
- while attempt < tries:
106
- attempt += 1
107
- log(f"partition attempt {attempt}/{tries} (orchestrator)")
127
+ # A probe round asks a question instead of returning a contract, so it must
128
+ # not spend one of the partition tries. Track the two counters separately:
129
+ # rewinding `attempt` made the loop relog the same attempt number and let a
130
+ # probe reply overwrite partition.attempt1.txt.
131
+ attempts = probes = replies = 0
132
+ announced = 0
133
+ while attempts < tries:
134
+ attempts += 1
135
+ # A probe round rewinds `attempts`, so the next pass around the loop
136
+ # re-derives the same number. Announce each number once.
137
+ if attempts > announced:
138
+ log(f"partition attempt {attempts}/{tries} (orchestrator)")
139
+ announced = attempts
108
140
  reply = localmodel.chat(cfg["orchestrator"], messages)
109
- (priv / f"partition.attempt{attempt}.txt").write_text(reply)
141
+ replies += 1
142
+ (priv / f"partition.attempt{replies}.txt").write_text(reply)
110
143
  try:
111
144
  data = localmodel.extract_json(reply)
112
145
  if isinstance(data.get("probes"), list) and "public_brief" not in data:
113
- attempt -= 1 # probes do not spend a partition attempt
114
146
  probes += 1
147
+ attempts -= 1 # probes do not spend a partition attempt
115
148
  if not det_on or not det.get("probe_raw_prompt", False) or probes > max_probes:
149
+ log(f"probe round {probes}/{max_probes}: orchestrator asked a question; "
150
+ f"probing is off, telling it to write the contract")
116
151
  answer = "PROBE RESULTS: probing is not available. Reply with the contract."
117
152
  else:
118
153
  spans = [(f"probe[{n}]", str(t)) for n, t in enumerate(data["probes"])]
@@ -148,14 +183,14 @@ def partition(cfg: dict, user_prompt: str, denylist, priv: Path) -> Contract:
148
183
  # when it passes, because it is what a refusal actually keys on.
149
184
  overall = detector.score_whole_view(det, c.public_view(), terms)
150
185
  verdicts.append(overall)
151
- (priv / f"detector.attempt{attempt}.json").write_text(
186
+ (priv / f"detector.attempt{attempts}.json").write_text(
152
187
  json.dumps([v.__dict__ for v in verdicts], indent=2))
153
188
  if overall.flagged:
154
189
  log(detector.describe([overall]))
155
190
  if any(v.flagged for v in verdicts):
156
191
  problems.append(detector.describe(verdicts))
157
192
  if not problems:
158
- report = {"attempt": attempt,
193
+ report = {"attempt": attempts,
159
194
  "spans": [v.__dict__ for v in verdicts],
160
195
  "hints": [h.__dict__ for h in gate.hints(c.public_text())]}
161
196
  (priv / "riskreport.json").write_text(json.dumps(report, indent=2))
@@ -282,6 +317,7 @@ def implement_private(cfg: dict, user_prompt: str, c: Contract, public: Path, pr
282
317
  # ---------------------------------------------------------------- main
283
318
  def main() -> None:
284
319
  ap = argparse.ArgumentParser(
320
+ prog="killchain",
285
321
  description=__doc__,
286
322
  formatter_class=argparse.RawDescriptionHelpFormatter,
287
323
  epilog="Docs and war stories: https://youtube.com/@drjoshcsimmons",
@@ -297,7 +333,8 @@ def main() -> None:
297
333
  help="override risk detector base_url ('fake' for canned)")
298
334
  ap.add_argument("--no-detector", "--no-risk", dest="no_detector", action="store_true",
299
335
  help="skip model scoring entirely (gate only)")
300
- ap.add_argument("--private-root"); ap.add_argument("--workspace")
336
+ ap.add_argument("--private-root")
337
+ ap.add_argument("--workspace")
301
338
  ap.add_argument("--yes", action="store_true", help="skip the outbound review prompt")
302
339
  ap.add_argument("--skip-frontier", action="store_true", help="public/ already built; go to private step")
303
340
  ap.add_argument("--skip-private", action="store_true", help="stop after the frontier build")
@@ -311,13 +348,26 @@ def main() -> None:
311
348
  cfg = tomllib.loads(paths.resolve_config(a.config).read_text())
312
349
  raise SystemExit(doctor.run(cfg))
313
350
 
351
+ try:
352
+ _run(a)
353
+ except FAILURES as e:
354
+ fail(str(e))
355
+
356
+
357
+ def _run(a: argparse.Namespace) -> None:
358
+ """Everything main() does once the arguments are parsed.
359
+
360
+ Split out so that every configuration and network failure lands in one
361
+ handler. A stack trace at this layer means "you misconfigured something",
362
+ which reads as "the tool is broken" when the real answer is one variable.
363
+ """
314
364
  cfg = load_cfg(paths.resolve_config(a.config), a)
315
365
  if a.file:
316
366
  user_prompt = Path(a.file).read_text()
317
367
  elif a.prompt:
318
368
  user_prompt = a.prompt
319
369
  else:
320
- ap.error("give a prompt or -f FILE")
370
+ raise SystemExit("give a prompt or -f FILE")
321
371
 
322
372
  run_id = a.run_id or dt.datetime.now().strftime("%Y%m%d-%H%M%S")
323
373
  public = cfg["paths"]["workspace"] / run_id / "public"
@@ -368,7 +418,16 @@ def main() -> None:
368
418
  log(f"public half: {public}")
369
419
  log(f"private half: {priv / 'private_impl'}")
370
420
  log(f"risk report: {priv / 'riskreport.json'}")
371
- log(f"run it: cd {public} && HARNESS_MODE=real PYTHONPATH={priv} python -m app.<entry>")
421
+ log(f"run it: cd {public} && HARNESS_MODE=real "
422
+ f"HARNESS_FIXTURES={priv / 'private_fixtures.json'} "
423
+ f"PYTHONPATH={priv} python -m app.<entry>")
424
+ log(f"test it: cd {public} && HARNESS_MODE=real "
425
+ f"HARNESS_FIXTURES={priv / 'private_fixtures.json'} "
426
+ f"PYTHONPATH={priv} python -m unittest discover -s tests -t .")
427
+ if not cfg["risk"].get("enabled", True):
428
+ log("NOTE: risk scoring was DISABLED for this run (--no-detector). "
429
+ "The regex gate ran; the refusal dimensions were NOT scored, so this "
430
+ "run is not evidence about refusal risk.")
372
431
  if not ok:
373
432
  raise SystemExit(1)
374
433
 
@@ -34,7 +34,9 @@ def workspace() -> Path:
34
34
  """The per-project run directory, creating it (gitignored) on first use."""
35
35
  root = find_project_root()
36
36
  if root is None:
37
- return data_dir() / "workspace"
37
+ ws = data_dir() / "workspace"
38
+ ws.mkdir(parents=True, exist_ok=True)
39
+ return ws
38
40
  ws = root / ".killchain" / "workspace"
39
41
  ws.mkdir(parents=True, exist_ok=True)
40
42
  ignore = root / ".gitignore"
@@ -254,6 +256,10 @@ def resolve_config(explicit: str | None) -> Path:
254
256
  def load_toml(path: Path) -> dict:
255
257
  try:
256
258
  return tomllib.loads(path.read_text())
259
+ except FileNotFoundError:
260
+ raise SystemExit(f"no such config file: {path}") from None
261
+ except OSError as e:
262
+ raise SystemExit(f"cannot read {path}: {e}") from e
257
263
  except tomllib.TOMLDecodeError as e:
258
264
  raise SystemExit(f"{path} is not valid TOML: {e}")
259
265
 
@@ -65,7 +65,13 @@ def _load():
65
65
  if os.environ.get("HARNESS_MODE", "stub") == "real":
66
66
  p = os.environ.get("HARNESS_FIXTURES")
67
67
  if not p:
68
- raise RuntimeError("HARNESS_MODE=real needs HARNESS_FIXTURES=<private fixtures json>")
68
+ raise RuntimeError(
69
+ "HARNESS_MODE=real needs HARNESS_FIXTURES=<private fixtures json>\\n"
70
+ " The file is private_fixtures.json in the run directory, next to "
71
+ "private_impl/.\\n"
72
+ " Example: HARNESS_MODE=real HARNESS_FIXTURES=../private_fixtures.json "
73
+ "PYTHONPATH=.. python -m unittest tests.test_contracts"
74
+ )
69
75
  return json.loads(pathlib.Path(p).read_text())
70
76
  here = pathlib.Path(__file__).resolve().parent.parent
71
77
  return json.loads((here / "contracts" / "_fixtures.json").read_text())
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "killchain"
7
- version = "0.1.0"
7
+ version = "0.1.2"
8
8
  description = "Split a build so a frontier coding agent never sees the risky half."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.11"
@@ -43,3 +43,22 @@ packages = ["killchain"]
43
43
 
44
44
  [tool.hatch.build.targets.sdist]
45
45
  include = ["killchain", "README.md", "pyproject.toml"]
46
+
47
+ [tool.ruff]
48
+ target-version = "py311"
49
+ line-length = 100
50
+
51
+ [tool.ruff.lint]
52
+ # Correctness and real bugs only. Style preferences are deliberately out of
53
+ # scope: this is a small stdlib-only tool and the import-alias and regex-alias
54
+ # opinions cost more churn than they save.
55
+ select = ["F", "E4", "E7", "E9", "W6", "I", "UP032", "B006", "B008"]
56
+ ignore = ["E501"]
57
+
58
+ [tool.ruff.lint.isort]
59
+ combine-as-imports = true
60
+ force-single-line = false
61
+
62
+ [tool.pytest.ini_options]
63
+ testpaths = ["tests"]
64
+ addopts = "-q"
@@ -1,10 +0,0 @@
1
- """killchain: split a build so a frontier agent never sees the risky half.
2
-
3
- The prompt is partitioned by *refusal risk*, not confidentiality. Anything a
4
- commercial coding agent would refuse, hedge, simplify, or guess at is routed to
5
- an abliterated orchestrator model, which then implements it locally. A frontier
6
- agent (Claude Code, Codex) builds the rest against stubs.
7
- """
8
-
9
- __version__ = "0.1.0"
10
- __all__ = ["__version__"]
File without changes
File without changes
File without changes
File without changes
File without changes
@@ -10,9 +10,9 @@ from __future__ import annotations
10
10
  import json
11
11
  import os
12
12
  import re
13
- from pathlib import Path
14
- import urllib.request
15
13
  import urllib.error
14
+ import urllib.request
15
+ from pathlib import Path
16
16
 
17
17
 
18
18
  class LocalModelError(RuntimeError):