kanit-gates 0.1.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.
- kanit/__init__.py +6 -0
- kanit/__main__.py +5 -0
- kanit/audit.py +168 -0
- kanit/cli.py +419 -0
- kanit/engine.py +475 -0
- kanit/rules/core.json +2201 -0
- kanit/rules/tr.json +181 -0
- kanit/transcript.py +186 -0
- kanit_gates-0.1.0.dist-info/METADATA +326 -0
- kanit_gates-0.1.0.dist-info/RECORD +15 -0
- kanit_gates-0.1.0.dist-info/WHEEL +5 -0
- kanit_gates-0.1.0.dist-info/entry_points.txt +2 -0
- kanit_gates-0.1.0.dist-info/licenses/LICENSE +202 -0
- kanit_gates-0.1.0.dist-info/licenses/NOTICE +4 -0
- kanit_gates-0.1.0.dist-info/top_level.txt +1 -0
kanit/__init__.py
ADDED
kanit/__main__.py
ADDED
kanit/audit.py
ADDED
|
@@ -0,0 +1,168 @@
|
|
|
1
|
+
"""Append-only audit log and loud failure reporting.
|
|
2
|
+
|
|
3
|
+
Lesson from production (04.11.2026): our engine crashed on a missing rule field ~906 times
|
|
4
|
+
in nine hours and failed open; every gate silently stopped working. Here a crash still lets
|
|
5
|
+
the session continue (unless KANIT_FAIL_CLOSED=1), but it is logged and shown on screen.
|
|
6
|
+
Logging itself never raises: a log that cannot be written must not take a decision down with it.
|
|
7
|
+
"""
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import hashlib
|
|
11
|
+
import json
|
|
12
|
+
import os
|
|
13
|
+
import sys
|
|
14
|
+
import tempfile
|
|
15
|
+
import time
|
|
16
|
+
|
|
17
|
+
WARN_EVERY_S = 600
|
|
18
|
+
ROTATE_BYTES = 20 * 1024 * 1024 # a log above this is moved to <name>.1 (one generation kept)
|
|
19
|
+
_NOFOLLOW = getattr(os, "O_NOFOLLOW", 0)
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
def project_dir() -> str:
|
|
23
|
+
"""The project root. Claude Code sets CLAUDE_PROJECT_DIR for hooks; unlike the hook's `cwd` it does
|
|
24
|
+
not follow a `cd` inside the session, so `cd src/api` cannot step out of the project's rules."""
|
|
25
|
+
p = os.environ.get("CLAUDE_PROJECT_DIR")
|
|
26
|
+
return p if p and os.path.isdir(p) else os.getcwd()
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def home() -> str:
|
|
30
|
+
return os.environ.get("KANIT_HOME") or os.path.join(project_dir(), ".kanit")
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
# Logs live next to the project's rules; keep them out of git, keep rules.json in.
|
|
34
|
+
GITIGNORE = "# written by kanit: logs stay local, rules.json is meant to be committed\n*.jsonl\n*.jsonl.1\nfailure.json\n"
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def ensure_home() -> str:
|
|
38
|
+
"""Create the audit directory on first use, with a .gitignore so logs are never committed by accident."""
|
|
39
|
+
h = home()
|
|
40
|
+
os.makedirs(h, exist_ok=True)
|
|
41
|
+
gi = os.path.join(h, ".gitignore")
|
|
42
|
+
if not os.path.lexists(gi):
|
|
43
|
+
fd = os.open(gi, os.O_WRONLY | os.O_CREAT | os.O_EXCL | _NOFOLLOW, 0o644)
|
|
44
|
+
with os.fdopen(fd, "w", encoding="utf-8") as f:
|
|
45
|
+
f.write(GITIGNORE)
|
|
46
|
+
return h
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def _append(name: str, row: dict) -> None:
|
|
50
|
+
path = os.path.join(home(), name)
|
|
51
|
+
try:
|
|
52
|
+
ensure_home()
|
|
53
|
+
row = dict(row, t=row.get("t") or time.time())
|
|
54
|
+
line = json.dumps(row, ensure_ascii=True) + "\n" # ASCII: lone surrogates and odd code pages cannot break it
|
|
55
|
+
try:
|
|
56
|
+
if os.lstat(path).st_size > ROTATE_BYTES:
|
|
57
|
+
os.replace(path, path + ".1")
|
|
58
|
+
except OSError:
|
|
59
|
+
pass
|
|
60
|
+
# O_NOFOLLOW: a planted symlink (.kanit/evals.jsonl -> ~/.bashrc) is refused, not appended to
|
|
61
|
+
fd = os.open(path, os.O_WRONLY | os.O_APPEND | os.O_CREAT | _NOFOLLOW, 0o644)
|
|
62
|
+
with os.fdopen(fd, "a", encoding="utf-8") as f:
|
|
63
|
+
f.write(line)
|
|
64
|
+
except Exception as e: # never raise, never swallow silently
|
|
65
|
+
try:
|
|
66
|
+
sys.stderr.write("kanit: audit write failed (%s): %r\n" % (path, e))
|
|
67
|
+
except Exception:
|
|
68
|
+
pass
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
def read_jsonl(name: str) -> list:
|
|
72
|
+
path = os.path.join(home(), name)
|
|
73
|
+
rows = []
|
|
74
|
+
try:
|
|
75
|
+
with open(path, encoding="utf-8", errors="replace") as f:
|
|
76
|
+
for line in f:
|
|
77
|
+
try:
|
|
78
|
+
rows.append(json.loads(line))
|
|
79
|
+
except ValueError:
|
|
80
|
+
continue
|
|
81
|
+
except OSError:
|
|
82
|
+
pass
|
|
83
|
+
return rows
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
def log_hit(session: str, event: str, rule: dict, excerpt: str, shadow: bool = False) -> None:
|
|
87
|
+
row = {"session": session, "event": event, "rule": rule["id"], "action": rule["action"], "excerpt": excerpt[:160]}
|
|
88
|
+
if shadow:
|
|
89
|
+
row["shadow"] = True
|
|
90
|
+
_append("audit.jsonl", row)
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
def log_eval(session: str, event: str, evaluated: list, hits: list, **extra) -> None:
|
|
94
|
+
"""Denominator for every rule: how often it was checked, not only how often it fired."""
|
|
95
|
+
_append("evals.jsonl", dict({"session": session, "event": event, "evaluated": evaluated, "hits": hits}, **extra))
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
def _throttle(key: str, now: float) -> tuple:
|
|
99
|
+
"""Count events per hour under `key`; return (show_warning_now, count_last_hour)."""
|
|
100
|
+
path = os.path.join(home(), "failure.json")
|
|
101
|
+
try:
|
|
102
|
+
with open(path, encoding="utf-8") as f:
|
|
103
|
+
state = json.load(f)
|
|
104
|
+
if not isinstance(state, dict):
|
|
105
|
+
state = {}
|
|
106
|
+
except (OSError, ValueError):
|
|
107
|
+
state = {}
|
|
108
|
+
s = state.get(key) if isinstance(state.get(key), dict) else {}
|
|
109
|
+
if now - s.get("last", 0) > 3600:
|
|
110
|
+
s["count"] = 0
|
|
111
|
+
s["count"] = s.get("count", 0) + 1
|
|
112
|
+
s["last"] = now
|
|
113
|
+
show = now - s.get("last_warned", 0) > WARN_EVERY_S
|
|
114
|
+
if show:
|
|
115
|
+
s["last_warned"] = now
|
|
116
|
+
state[key] = s
|
|
117
|
+
if len(state) > 200: # keep the newest keys only
|
|
118
|
+
state = dict(sorted(state.items(), key=lambda kv: -(kv[1].get("last", 0) if isinstance(kv[1], dict) else 0))[:100])
|
|
119
|
+
try:
|
|
120
|
+
ensure_home()
|
|
121
|
+
fd, tmp = tempfile.mkstemp(dir=home(), prefix=".failure-")
|
|
122
|
+
with os.fdopen(fd, "w", encoding="utf-8") as f:
|
|
123
|
+
json.dump(state, f)
|
|
124
|
+
os.replace(tmp, path) # replaces a planted symlink instead of writing through it
|
|
125
|
+
except Exception as e:
|
|
126
|
+
try:
|
|
127
|
+
sys.stderr.write("kanit: failure state write failed: %r\n" % e)
|
|
128
|
+
except Exception:
|
|
129
|
+
pass
|
|
130
|
+
return show, s["count"]
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
def _key(kind: str, text: str) -> str:
|
|
134
|
+
"""One throttle per distinct problem: a second, different error is never hidden behind the first."""
|
|
135
|
+
return "%s:%s" % (kind, hashlib.sha256(text.encode("utf-8", "replace")).hexdigest()[:16])
|
|
136
|
+
|
|
137
|
+
|
|
138
|
+
def fail_loud(exc: BaseException, now: float = 0.0) -> str:
|
|
139
|
+
"""Record an engine failure; return the on-screen warning ("" while throttled).
|
|
140
|
+
|
|
141
|
+
The caller prints it inside its single JSON object: a hook must emit exactly one.
|
|
142
|
+
"""
|
|
143
|
+
now = now or time.time()
|
|
144
|
+
text = repr(exc)[:200]
|
|
145
|
+
_append("audit.jsonl", {"event": "engine_error", "error": text})
|
|
146
|
+
show, count = _throttle(_key("engine_error", type(exc).__name__ + str(exc)[:80]), now)
|
|
147
|
+
if not show:
|
|
148
|
+
return ""
|
|
149
|
+
return ("kanit ENGINE ERROR: gates are NOT enforcing (%d times in the last hour). Last: %s. Log: %s"
|
|
150
|
+
% (count, repr(exc)[:120], os.path.join(home(), "audit.jsonl")))
|
|
151
|
+
|
|
152
|
+
|
|
153
|
+
def rule_errors(errors: list, now: float = 0.0) -> str:
|
|
154
|
+
"""Invalid rules are skipped, never fatal; return a throttled warning text ("" when quiet)."""
|
|
155
|
+
if not errors:
|
|
156
|
+
return ""
|
|
157
|
+
now = now or time.time()
|
|
158
|
+
_append("audit.jsonl", {"event": "rule_error", "errors": errors[:20]})
|
|
159
|
+
show, _ = _throttle(_key("rule_error", "\n".join(errors)), now)
|
|
160
|
+
if not show:
|
|
161
|
+
return ""
|
|
162
|
+
return "kanit: %d invalid rule(s) skipped, the rest still enforce: %s" % (len(errors), "; ".join(errors[:3]))
|
|
163
|
+
|
|
164
|
+
|
|
165
|
+
def notice(key: str, text: str, now: float = 0.0) -> str:
|
|
166
|
+
"""A one-off notice for the human: returned the first time `key` is seen within the hour, then ""."""
|
|
167
|
+
show, count = _throttle(_key("notice", key), now or time.time())
|
|
168
|
+
return text if show and count == 1 else ""
|
kanit/cli.py
ADDED
|
@@ -0,0 +1,419 @@
|
|
|
1
|
+
"""Command line: hook | test-rules | stats | doctor."""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
import argparse
|
|
5
|
+
import hashlib
|
|
6
|
+
import json
|
|
7
|
+
import os
|
|
8
|
+
import signal
|
|
9
|
+
import stat
|
|
10
|
+
import sys
|
|
11
|
+
import time
|
|
12
|
+
|
|
13
|
+
from . import __version__, audit, engine, transcript
|
|
14
|
+
|
|
15
|
+
RULES_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "rules")
|
|
16
|
+
CORE_RULES = os.path.join(RULES_DIR, "core.json")
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
def packaged_rules() -> list:
|
|
20
|
+
"""core.json first, then the other packaged rule sets (e.g. tr.json) in name order."""
|
|
21
|
+
extra = sorted(os.path.join(RULES_DIR, f) for f in os.listdir(RULES_DIR) if f.endswith(".json") and f != "core.json")
|
|
22
|
+
return [CORE_RULES] + extra
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
def shadow() -> bool:
|
|
26
|
+
"""KANIT_SHADOW=1: evaluate and log everything, print nothing. For trying kanit on real traffic."""
|
|
27
|
+
return os.environ.get("KANIT_SHADOW") == "1"
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def rule_paths() -> list:
|
|
31
|
+
"""Packaged rules, then project rules (.kanit/rules.json), then KANIT_RULES (os.pathsep list)."""
|
|
32
|
+
paths = packaged_rules()
|
|
33
|
+
project = os.path.join(audit.project_dir(), ".kanit", "rules.json")
|
|
34
|
+
if os.path.exists(project):
|
|
35
|
+
paths.append(project)
|
|
36
|
+
paths.extend(p for p in os.environ.get("KANIT_RULES", "").split(os.pathsep) if p)
|
|
37
|
+
return paths
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def _disabled() -> list:
|
|
41
|
+
# set by the human in the environment of the hook process; the agent cannot change it
|
|
42
|
+
return [x.strip() for x in os.environ.get("KANIT_DISABLE", "").split(",") if x.strip()]
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def _emit(obj: dict) -> None:
|
|
46
|
+
# ASCII-only JSON: the hook's stdout may use any code page (cp1252 on Windows); \uXXXX always prints
|
|
47
|
+
print(json.dumps(obj, ensure_ascii=True))
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def _read_payload(stream) -> dict:
|
|
51
|
+
"""Claude Code sends UTF-8. Read bytes when we can, so the console code page never decides."""
|
|
52
|
+
buf = getattr(stream, "buffer", None)
|
|
53
|
+
raw = buf.read().decode("utf-8", "replace") if buf is not None else stream.read()
|
|
54
|
+
payload = json.loads(raw)
|
|
55
|
+
if not isinstance(payload, dict):
|
|
56
|
+
raise ValueError("hook payload is not a JSON object")
|
|
57
|
+
return payload
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
PRIOR_MAX_BYTES = 2 * 1024 * 1024
|
|
61
|
+
# Claude Code lets a call through when a hook times out (10 s PreToolUse, 20 s Stop here), so kanit
|
|
62
|
+
# stops itself first and decides on purpose instead of timing out open.
|
|
63
|
+
BUDGET_S = {"PreToolUse": 6.0, "Stop": 14.0, "SubagentStop": 14.0}
|
|
64
|
+
DEFAULT_BUDGET_S = 6.0
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
class OverBudget(Exception):
|
|
68
|
+
"""Raised by the timer when evaluation takes longer than the event's budget."""
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
def _arm(seconds: float) -> None:
|
|
72
|
+
if not hasattr(signal, "setitimer"): # Windows: no interval timer, Claude Code's own timeout applies
|
|
73
|
+
return
|
|
74
|
+
|
|
75
|
+
def _expired(signum, frame):
|
|
76
|
+
raise OverBudget()
|
|
77
|
+
|
|
78
|
+
signal.signal(signal.SIGALRM, _expired)
|
|
79
|
+
signal.setitimer(signal.ITIMER_REAL, seconds)
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
def _disarm() -> None:
|
|
83
|
+
if hasattr(signal, "setitimer"):
|
|
84
|
+
signal.setitimer(signal.ITIMER_REAL, 0)
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
def with_prior(tool_input: dict) -> dict:
|
|
88
|
+
"""For a Write that replaces an existing file, add its current text as "_prior", so "only_added"
|
|
89
|
+
rules compare against what is already there. Missing, unreadable, special (FIFO, device) or very
|
|
90
|
+
large files count as empty."""
|
|
91
|
+
path = tool_input.get("file_path")
|
|
92
|
+
if "content" not in tool_input or not isinstance(path, str) or not path:
|
|
93
|
+
return tool_input
|
|
94
|
+
try:
|
|
95
|
+
st = os.stat(path)
|
|
96
|
+
if not stat.S_ISREG(st.st_mode) or st.st_size > PRIOR_MAX_BYTES:
|
|
97
|
+
return tool_input
|
|
98
|
+
with open(path, encoding="utf-8", errors="replace") as f:
|
|
99
|
+
return dict(tool_input, _prior=f.read(PRIOR_MAX_BYTES + 1))
|
|
100
|
+
except (OSError, ValueError):
|
|
101
|
+
return tool_input
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
def weakened(rules: list) -> list:
|
|
105
|
+
"""Packaged rules that project files or KANIT_RULES turned off or changed (KANIT_DISABLE is the
|
|
106
|
+
human's own switch and is not counted). The agent may find a way to write .kanit/rules.json, so
|
|
107
|
+
the human is told whenever it weakens the packaged set."""
|
|
108
|
+
base = {r["id"]: r for r in engine.load_rules(packaged_rules())[0]}
|
|
109
|
+
final = {r["id"]: r for r in rules}
|
|
110
|
+
return sorted(rid for rid in base if final.get(rid) != base[rid])
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
def _weakened_note(session: str) -> str:
|
|
114
|
+
extra = rule_paths()[len(packaged_rules()):]
|
|
115
|
+
if not extra:
|
|
116
|
+
return ""
|
|
117
|
+
ids = weakened(engine.load_rules(rule_paths())[0])
|
|
118
|
+
if not ids:
|
|
119
|
+
return ""
|
|
120
|
+
digest = hashlib.sha256()
|
|
121
|
+
for p in extra:
|
|
122
|
+
try:
|
|
123
|
+
digest.update(engine.read_rules_file_bytes(p))
|
|
124
|
+
except (OSError, ValueError):
|
|
125
|
+
digest.update(p.encode("utf-8", "replace"))
|
|
126
|
+
text = ("kanit: project rules turn off or change %d packaged rule(s): %s. If you did not make this change, "
|
|
127
|
+
"check %s." % (len(ids), ", ".join(ids[:8]) + (" ..." if len(ids) > 8 else ""), ", ".join(extra)))
|
|
128
|
+
return audit.notice(session + ":" + digest.hexdigest(), text)
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
def run_hook(payload: dict) -> int:
|
|
132
|
+
if payload.get("cwd") and isinstance(payload["cwd"], str) and os.path.isdir(payload["cwd"]):
|
|
133
|
+
os.chdir(payload["cwd"])
|
|
134
|
+
event_name = payload.get("hook_event_name", "")
|
|
135
|
+
session = str(payload.get("session_id", ""))
|
|
136
|
+
rules, errors = engine.load_rules(rule_paths(), _disabled())
|
|
137
|
+
note = audit.rule_errors(errors)
|
|
138
|
+
extra_log = {}
|
|
139
|
+
|
|
140
|
+
if event_name == "PreToolUse":
|
|
141
|
+
event, tool = "tool", str(payload.get("tool_name", ""))
|
|
142
|
+
applicable = [r for r in rules if engine.applies(r, event, tool)]
|
|
143
|
+
tool_input = payload.get("tool_input") or {}
|
|
144
|
+
if not isinstance(tool_input, dict):
|
|
145
|
+
tool_input = {}
|
|
146
|
+
if any(r.get("only_added") for r in applicable):
|
|
147
|
+
tool_input = with_prior(tool_input)
|
|
148
|
+
hits = engine.tool_hits(applicable, tool, tool_input)
|
|
149
|
+
elif event_name in ("Stop", "SubagentStop"):
|
|
150
|
+
event = "reply"
|
|
151
|
+
applicable = [r for r in rules if engine.applies(r, event)]
|
|
152
|
+
# a subagent's reply is judged on the subagent's own transcript
|
|
153
|
+
path = payload.get("agent_transcript_path") or payload.get("transcript_path") or ""
|
|
154
|
+
path = path if isinstance(path, str) else ""
|
|
155
|
+
reply = payload.get("last_assistant_message")
|
|
156
|
+
reply = reply if isinstance(reply, str) and reply else transcript.last_reply(path)
|
|
157
|
+
acts, started = transcript.turn_state(path)
|
|
158
|
+
if not started:
|
|
159
|
+
# the turn began outside what we can read (compaction, very long turn): its evidence is
|
|
160
|
+
# unknown, so rules that need this turn's tool calls are not applied rather than misfiring
|
|
161
|
+
applicable = [r for r in applicable if not r.get("needs_turn")]
|
|
162
|
+
extra_log["turn_unknown"] = True
|
|
163
|
+
turn = ["%s: %s" % (a["tool"], a["text"]) for a in acts]
|
|
164
|
+
seen = transcript.session_text(path) if any(r.get("check") == "urls_seen" for r in applicable) else ""
|
|
165
|
+
hits = engine.reply_hits(applicable, reply, turn, seen)
|
|
166
|
+
if any(r.get("check") == "urls_seen" for r, _ in hits) and transcript.longer_than_tail(path):
|
|
167
|
+
# a link given early in a long session is outside the tail we read: look it up in the whole file
|
|
168
|
+
seen += "\n" + transcript.older_text_with(path, engine.URL_RE.findall(reply))
|
|
169
|
+
hits = engine.reply_hits(applicable, reply, turn, seen)
|
|
170
|
+
else:
|
|
171
|
+
if note and not shadow():
|
|
172
|
+
_emit({"systemMessage": note})
|
|
173
|
+
return 0
|
|
174
|
+
|
|
175
|
+
audit.log_eval(session, event, [r["id"] for r in applicable], [r["id"] for r, _ in hits], **extra_log)
|
|
176
|
+
for r, excerpt in hits:
|
|
177
|
+
audit.log_hit(session, event, r, excerpt, shadow=shadow())
|
|
178
|
+
if shadow():
|
|
179
|
+
return 0
|
|
180
|
+
out = engine.decide(hits, event, bool(payload.get("stop_hook_active"))) or {}
|
|
181
|
+
for extra in (note, _weakened_note(session)):
|
|
182
|
+
if extra:
|
|
183
|
+
out["systemMessage"] = (out.get("systemMessage", "") + "\n" + extra).strip()
|
|
184
|
+
if out:
|
|
185
|
+
_emit(out)
|
|
186
|
+
return 0
|
|
187
|
+
|
|
188
|
+
|
|
189
|
+
def _over_budget(payload: dict) -> int:
|
|
190
|
+
event_name = payload.get("hook_event_name", "") if isinstance(payload, dict) else ""
|
|
191
|
+
budget = BUDGET_S.get(event_name, DEFAULT_BUDGET_S)
|
|
192
|
+
audit._append("audit.jsonl", {"session": str(payload.get("session_id", "")) if isinstance(payload, dict) else "",
|
|
193
|
+
"event": "over_budget", "hook": event_name, "budget_s": budget})
|
|
194
|
+
if shadow():
|
|
195
|
+
return 0
|
|
196
|
+
if event_name == "PreToolUse":
|
|
197
|
+
_emit({"hookSpecificOutput": {
|
|
198
|
+
"hookEventName": "PreToolUse", "permissionDecision": "deny",
|
|
199
|
+
"permissionDecisionReason": ("kanit could not finish checking this call within %.0f s (a very large or "
|
|
200
|
+
"unusual input). Split the command, or write long content with the "
|
|
201
|
+
"Write tool." % budget)}})
|
|
202
|
+
else:
|
|
203
|
+
_emit({"systemMessage": "kanit warning: this reply could not be checked within %.0f s and was not checked." % budget})
|
|
204
|
+
return 0
|
|
205
|
+
|
|
206
|
+
|
|
207
|
+
def hook(stream=None) -> int:
|
|
208
|
+
payload = {}
|
|
209
|
+
try:
|
|
210
|
+
_arm(DEFAULT_BUDGET_S)
|
|
211
|
+
payload = _read_payload(stream or sys.stdin)
|
|
212
|
+
_arm(BUDGET_S.get(payload.get("hook_event_name"), DEFAULT_BUDGET_S))
|
|
213
|
+
return run_hook(payload)
|
|
214
|
+
except OverBudget:
|
|
215
|
+
_disarm()
|
|
216
|
+
return _over_budget(payload)
|
|
217
|
+
except Exception as e: # fail loud, then fail open (or closed when asked); one JSON object only
|
|
218
|
+
_disarm()
|
|
219
|
+
out = {}
|
|
220
|
+
warning = audit.fail_loud(e)
|
|
221
|
+
if warning:
|
|
222
|
+
out["systemMessage"] = warning
|
|
223
|
+
if os.environ.get("KANIT_FAIL_CLOSED") == "1" and isinstance(payload, dict) \
|
|
224
|
+
and payload.get("hook_event_name") == "PreToolUse":
|
|
225
|
+
out["hookSpecificOutput"] = {"hookEventName": "PreToolUse", "permissionDecision": "deny",
|
|
226
|
+
"permissionDecisionReason": "kanit engine error and KANIT_FAIL_CLOSED=1: %r" % e}
|
|
227
|
+
if out and not shadow(): # in shadow mode the error is still in audit.jsonl and `kanit doctor`
|
|
228
|
+
_emit(out)
|
|
229
|
+
return 0
|
|
230
|
+
finally:
|
|
231
|
+
_disarm()
|
|
232
|
+
|
|
233
|
+
|
|
234
|
+
def check(kind: str, text: str, tool: str = "", tool_input=None, turn=(), seen: str = "", out=None) -> int:
|
|
235
|
+
"""Dry run without Claude Code: which active rules fire on this tool call or reply.
|
|
236
|
+
|
|
237
|
+
Exit code: 1 when a deny rule fires, 0 otherwise (warn hits are printed but do not fail)."""
|
|
238
|
+
w = out or sys.stdout
|
|
239
|
+
rules, errors = engine.load_rules(rule_paths(), _disabled())
|
|
240
|
+
for e in errors:
|
|
241
|
+
w.write("PROBLEM %s\n" % e)
|
|
242
|
+
if kind == "reply":
|
|
243
|
+
hits = engine.reply_hits([r for r in rules if engine.applies(r, "reply")], text, list(turn), seen)
|
|
244
|
+
else:
|
|
245
|
+
if kind == "bash":
|
|
246
|
+
tool, tool_input = "Bash", {"command": text}
|
|
247
|
+
hits = engine.tool_hits([r for r in rules if engine.applies(r, "tool", tool)], tool, tool_input or {})
|
|
248
|
+
for r, excerpt in hits:
|
|
249
|
+
w.write('%-4s %s\n %s\n matched: "%s"\n' % (r["action"].upper(), r["id"], r["message"], excerpt[:80]))
|
|
250
|
+
if not hits:
|
|
251
|
+
w.write("pass: no rule fired (%d rules checked)\n" % len(rules))
|
|
252
|
+
return 1 if any(r["action"] == "deny" for r, _ in hits) else 0
|
|
253
|
+
|
|
254
|
+
|
|
255
|
+
def _first_sentence(msg: str) -> str:
|
|
256
|
+
cut = msg.find(". ")
|
|
257
|
+
return msg if cut < 0 else msg[:cut + 1]
|
|
258
|
+
|
|
259
|
+
|
|
260
|
+
def rules_table(paths=None, markdown: bool = False, out=None) -> int:
|
|
261
|
+
"""List active rules. --markdown prints the table used in README.md (a test keeps them equal)."""
|
|
262
|
+
w = out or sys.stdout
|
|
263
|
+
rules, errors = engine.load_rules(paths or rule_paths(), _disabled())
|
|
264
|
+
if markdown:
|
|
265
|
+
w.write("| id | on | action | what it stops |\n|---|---|---|---|\n")
|
|
266
|
+
for r in rules:
|
|
267
|
+
w.write("| `%s` | %s | %s | %s |\n" % (r["id"], r["event"], r["action"], _first_sentence(r["message"]).replace("|", "\\|")))
|
|
268
|
+
else:
|
|
269
|
+
for r in rules:
|
|
270
|
+
w.write("%-34s %-5s %-4s %s\n" % (r["id"], r["event"], r["action"], _first_sentence(r["message"])))
|
|
271
|
+
for e in errors:
|
|
272
|
+
w.write("PROBLEM %s\n" % e)
|
|
273
|
+
return 1 if errors else 0
|
|
274
|
+
|
|
275
|
+
|
|
276
|
+
def _fires(rule: dict, example: dict) -> bool:
|
|
277
|
+
if rule["event"] == "tool":
|
|
278
|
+
return bool(engine.tool_hits([rule], example.get("tool", "Bash"), example.get("input") or {}))
|
|
279
|
+
return bool(engine.reply_hits([rule], example.get("reply", ""), example.get("turn") or [], example.get("seen", "")))
|
|
280
|
+
|
|
281
|
+
|
|
282
|
+
def test_rules(paths=None) -> int:
|
|
283
|
+
"""Every rule must prove itself: at least one example it fires on, all misses stay quiet."""
|
|
284
|
+
rules, errors = engine.load_rules(paths or rule_paths())
|
|
285
|
+
failures = list(errors)
|
|
286
|
+
n_examples = 0
|
|
287
|
+
for r in rules:
|
|
288
|
+
ex = r.get("examples") or {}
|
|
289
|
+
if not ex.get("hit"):
|
|
290
|
+
failures.append("%s: no 'hit' example; a rule that never proves it fires is not a gate" % r["id"])
|
|
291
|
+
for e in ex.get("hit") or []:
|
|
292
|
+
n_examples += 1
|
|
293
|
+
if not _fires(r, e):
|
|
294
|
+
failures.append("%s: should fire on %s" % (r["id"], json.dumps(e, ensure_ascii=False)[:120]))
|
|
295
|
+
for e in ex.get("miss") or []:
|
|
296
|
+
n_examples += 1
|
|
297
|
+
if _fires(r, e):
|
|
298
|
+
failures.append("%s: should NOT fire on %s" % (r["id"], json.dumps(e, ensure_ascii=False)[:120]))
|
|
299
|
+
for f in failures:
|
|
300
|
+
print("FAIL " + f)
|
|
301
|
+
print("rules %d · examples %d · failures %d" % (len(rules), n_examples, len(failures)))
|
|
302
|
+
return 1 if failures else 0
|
|
303
|
+
|
|
304
|
+
|
|
305
|
+
def stats(window: int = 600, out=None) -> dict:
|
|
306
|
+
"""Per rule: times checked, raw hits, unique hits (same session + rule within `window` s = one)."""
|
|
307
|
+
table = {}
|
|
308
|
+
evals = audit.read_jsonl("evals.jsonl")
|
|
309
|
+
for row in evals:
|
|
310
|
+
for rid in row.get("evaluated") or []:
|
|
311
|
+
table.setdefault(rid, {"checked": 0, "raw": 0, "unique": 0})["checked"] += 1
|
|
312
|
+
last = {}
|
|
313
|
+
for row in sorted(audit.read_jsonl("audit.jsonl"), key=lambda x: x.get("t", 0)):
|
|
314
|
+
rid = row.get("rule")
|
|
315
|
+
if not rid:
|
|
316
|
+
continue
|
|
317
|
+
s = table.setdefault(rid, {"checked": 0, "raw": 0, "unique": 0})
|
|
318
|
+
s["raw"] += 1
|
|
319
|
+
key = (row.get("session"), rid)
|
|
320
|
+
if row.get("t", 0) - last.get(key, -1e18) > window:
|
|
321
|
+
s["unique"] += 1
|
|
322
|
+
last[key] = row.get("t", 0)
|
|
323
|
+
w = out or sys.stdout
|
|
324
|
+
w.write("%-36s %8s %6s %7s %7s\n" % ("rule", "checked", "raw", "unique", "rate"))
|
|
325
|
+
for rid, s in sorted(table.items(), key=lambda kv: -kv[1]["unique"]):
|
|
326
|
+
rate = "%.2f%%" % (100.0 * s["unique"] / s["checked"]) if s["checked"] else "n/a"
|
|
327
|
+
w.write("%-36s %8d %6d %7d %7s\n" % (rid, s["checked"], s["raw"], s["unique"], rate))
|
|
328
|
+
replies = [r for r in evals if r.get("event") == "reply"]
|
|
329
|
+
if replies:
|
|
330
|
+
w.write("\nreply checks: %d · turn start not readable (evidence rules skipped): %d\n"
|
|
331
|
+
% (len(replies), sum(1 for r in replies if r.get("turn_unknown"))))
|
|
332
|
+
return table
|
|
333
|
+
|
|
334
|
+
|
|
335
|
+
def doctor() -> int:
|
|
336
|
+
problems = []
|
|
337
|
+
print("kanit %s · python %s" % (__version__, sys.version.split()[0]))
|
|
338
|
+
if sys.version_info < (3, 9):
|
|
339
|
+
problems.append("python >= 3.9 required")
|
|
340
|
+
rules, errors = engine.load_rules(rule_paths(), _disabled())
|
|
341
|
+
problems.extend(errors)
|
|
342
|
+
print("rules: %d active from %s" % (len(rules), ", ".join(rule_paths())))
|
|
343
|
+
try:
|
|
344
|
+
audit.ensure_home()
|
|
345
|
+
probe = os.path.join(audit.home(), ".probe")
|
|
346
|
+
with open(probe, "w") as f:
|
|
347
|
+
f.write("ok")
|
|
348
|
+
os.remove(probe)
|
|
349
|
+
print("audit log: %s (writable)" % audit.home())
|
|
350
|
+
except OSError as e:
|
|
351
|
+
problems.append("audit dir not writable: %s" % e)
|
|
352
|
+
errs = [r for r in audit.read_jsonl("audit.jsonl") if r.get("event") == "engine_error" and r.get("t", 0) > time.time() - 86400]
|
|
353
|
+
if errs:
|
|
354
|
+
problems.append("%d engine errors in the last 24 h, last: %s" % (len(errs), errs[-1].get("error")))
|
|
355
|
+
day = [r for r in audit.read_jsonl("evals.jsonl") if r.get("event") == "reply" and r.get("t", 0) > time.time() - 86400]
|
|
356
|
+
unknown = sum(1 for r in day if r.get("turn_unknown"))
|
|
357
|
+
if unknown:
|
|
358
|
+
print("note: %d of %d reply checks in the last 24 h could not read the start of the turn (no transcript, "
|
|
359
|
+
"or a compaction); evidence rules were skipped for them" % (unknown, len(day)))
|
|
360
|
+
for p in problems:
|
|
361
|
+
print("PROBLEM " + p)
|
|
362
|
+
print("ok" if not problems else "%d problem(s)" % len(problems))
|
|
363
|
+
return 1 if problems else 0
|
|
364
|
+
|
|
365
|
+
|
|
366
|
+
def main(argv=None) -> int:
|
|
367
|
+
for s in (sys.stdout, sys.stderr): # human output on a narrow code page: replace, never crash
|
|
368
|
+
try:
|
|
369
|
+
s.reconfigure(errors="replace")
|
|
370
|
+
except (AttributeError, ValueError):
|
|
371
|
+
pass
|
|
372
|
+
ap = argparse.ArgumentParser(prog="kanit", description="Evidence gates for coding agents.")
|
|
373
|
+
ap.add_argument("--version", action="version", version="kanit " + __version__)
|
|
374
|
+
sub = ap.add_subparsers(dest="cmd")
|
|
375
|
+
sub.add_parser("hook", help="read a Claude Code hook payload on stdin")
|
|
376
|
+
c = sub.add_parser("check", help="dry run: which rules fire on a shell command, tool call or reply",
|
|
377
|
+
description="Examples: kanit check bash 'git push --force' "
|
|
378
|
+
"kanit check reply 'All tests pass.' --turn 'Edit: app.py' "
|
|
379
|
+
"kanit check tool Write --input '{\"file_path\": \".env\"}'")
|
|
380
|
+
c.add_argument("kind", choices=("bash", "tool", "reply"))
|
|
381
|
+
c.add_argument("text", help="the shell command, the tool name (kind tool) or the reply text")
|
|
382
|
+
c.add_argument("--input", default="{}", help="tool input as JSON (kind tool)")
|
|
383
|
+
c.add_argument("--turn", action="append", default=[], help="a tool call made this turn, e.g. 'Bash: pytest' (repeatable)")
|
|
384
|
+
c.add_argument("--seen", default="", help="text the agent saw this session (for the link rule)")
|
|
385
|
+
r = sub.add_parser("rules", help="list active rules")
|
|
386
|
+
r.add_argument("--markdown", action="store_true", help="print the README table")
|
|
387
|
+
t = sub.add_parser("test-rules", help="check every rule against its own examples")
|
|
388
|
+
t.add_argument("paths", nargs="*")
|
|
389
|
+
s = sub.add_parser("stats", help="per-rule checked / hit counts from the audit log")
|
|
390
|
+
s.add_argument("--window", type=int, default=600, help="dedupe window in seconds (default 600)")
|
|
391
|
+
sub.add_parser("doctor", help="check install, rules and audit log")
|
|
392
|
+
a = ap.parse_args(argv)
|
|
393
|
+
if a.cmd == "hook":
|
|
394
|
+
return hook()
|
|
395
|
+
if a.cmd == "check":
|
|
396
|
+
if a.kind == "tool":
|
|
397
|
+
try:
|
|
398
|
+
tool_input = json.loads(a.input)
|
|
399
|
+
except ValueError as e:
|
|
400
|
+
ap.error("--input is not valid JSON: %s" % e)
|
|
401
|
+
if not isinstance(tool_input, dict):
|
|
402
|
+
ap.error("--input must be a JSON object")
|
|
403
|
+
return check("tool", "", tool=a.text, tool_input=tool_input)
|
|
404
|
+
return check(a.kind, a.text, turn=a.turn, seen=a.seen)
|
|
405
|
+
if a.cmd == "rules":
|
|
406
|
+
return rules_table(markdown=a.markdown)
|
|
407
|
+
if a.cmd == "test-rules":
|
|
408
|
+
return test_rules(a.paths or None)
|
|
409
|
+
if a.cmd == "stats":
|
|
410
|
+
stats(a.window)
|
|
411
|
+
return 0
|
|
412
|
+
if a.cmd == "doctor":
|
|
413
|
+
return doctor()
|
|
414
|
+
ap.print_help()
|
|
415
|
+
return 2
|
|
416
|
+
|
|
417
|
+
|
|
418
|
+
if __name__ == "__main__":
|
|
419
|
+
sys.exit(main())
|