k9audit

Category: Tools & Productivity | Uploader: liuhaotian2024-prog | Downloads: 0 | Version: v1.0（Latest）

Changelog: Source: GitHub https://github.com/liuhaotian2024-prog/K9Audit

Directory Structure

Current level: Root

📁 .claude/
- 📄 settings.json 421 B
📁 .claude-plugin/
- 📄 plugin.json 1.0 KB
📁 .github/
- 📁 ISSUE_TEMPLATE/
  - 📄 hard_case.yml 2.1 KB
📁 challenge/
- 📁 examples/
  - 📄 case_000_live_verified.jsonl 14.3 KB
  - 📄 case_000_quant_trading_agent.md 9.2 KB
  - 📄 case_001_rebuild_loop.md 6.9 KB
  - 📄 case_002_live_verified.jsonl 17.4 KB
  - 📄 case_002_read_then_write.md 7.2 KB
  - 📄 case_003_live_verified.jsonl 46.1 KB
  - 📄 case_003_self_audit.md 5.7 KB
  - 📄 case_004_repo_residue.md 7.1 KB
- 📄 challenge_logs.jsonl 37.3 KB
- 📄 cieu_session.jsonl 34.7 KB
- 📄 README.md 7.9 KB
📁 commands/
- 📄 k9-audit.md 800 B
📁 concepts/
- 📄 cieu-five-tuple.mdx 74 B
📁 docs/
- 📄 causal_tracing.md 3.6 KB
- 📄 CIEU_spec.md 10.2 KB
- 📄 code_invariants.md 4.2 KB
- 📄 demo.gif 1.1 MB
- 📄 index.html 77.4 KB
- 📄 integrations.md 6.8 KB
- 📄 k9_demo.html 10.1 KB
- 📄 PRODUCT_VISION.md 5.5 KB
- 📄 roadmap_phase2.md 1.4 KB
- 📄 定位修正工作清单.md 5.8 KB
📁 k9log/
- 📁 governance/
  - 📄 __init__.py 962 B
  - 📄 action_class.py 2.1 KB
  - 📄 grants.py 7.7 KB
  - 📄 types.py 3.2 KB
- 📁 openclaw_adapter/
  - 📄 __init__.py 506 B
  - 📄 mapping.py 4.6 KB
  - 📄 normalize.py 6.3 KB
- 📄 __init__.py 3.4 KB
- 📄 __main__.py 109 B
- 📄 agents_md_parser.py 11.2 KB
- 📄 alerting.py 20.8 KB
- 📄 auditor.py 17.7 KB
- 📄 autocontract.py 7.5 KB
- 📄 causal_analyzer.py 15.1 KB
- 📄 cli.py 68.1 KB
- 📄 constraints.py 35.5 KB
- 📄 core.py 17.5 KB
- 📄 hook.py 7.4 KB
- 📄 hook_post.py 13.7 KB
- 📄 identity.py 5.1 KB
- 📄 langchain_adapter.py 7.2 KB
- 📄 ledger_sync.py 12.6 KB
- 📄 logger.py 17.3 KB
- 📄 openclaw.py 5.8 KB
- 📄 openclaw_watcher.py 14.0 KB
- 📄 redact.py 7.1 KB
- 📄 report.py 20.7 KB
- 📄 tracer.py 7.5 KB
- 📄 verifier.py 9.4 KB
📁 server/
- 📄 dashboard.html 17.0 KB
- 📄 main.py 12.0 KB
- 📄 requirements.txt 59 B
📁 skills/
- 📁 k9audit/
  - 📄 setup.sh 3.3 KB
  - 📄 SKILL.md 2.4 KB
📄 .gitattributes 42 B
📄 .gitignore 2.2 KB
📄 AGENTS.md 2.3 KB
📄 check_frontend.ps1 1.9 KB
📄 claude_settings.json 217 B
📄 Install-K9Solo.ps1 9.2 KB
📄 introduction.mdx 90 B
📄 k9_case001_replay.py 8.2 KB
📄 k9_case002_replay.py 5.9 KB
📄 k9_case003_replay.py 15.0 KB
📄 k9_concurrency_test.py 9.7 KB
📄 k9_live_test.py 5.5 KB
📄 k9_repo_audit.py 13.9 KB
📄 k9_repo_cleanup.py 7.7 KB
📄 k9audit_cieu_simulation.py 9.2 KB
📄 k9audit_openclaw_test.py 16.0 KB
📄 LICENSE 694 B
📄 mint.json 534 B
📄 PATENTS.md 1.5 KB
📄 push_safe.ps1 2.0 KB
📄 pyproject.toml 525 B
📄 quickstart.mdx 57 B
📄 README.md 42.5 KB
📄 release.ps1 1.0 KB
📄 requirements.txt 145 B
📄 setup_k9audit.ps1 1.6 KB
📄 SKILL.md 4.0 KB

SKILL.md

---
name: k9audit
description: >-
  Causal audit for AI agents — records every OpenClaw tool call as a CIEU
  five-tuple including Y*_t (intent contract). Answers the question no logger
  can: "Did the agent see the constraint before it violated it?"
  Reads your AGENTS.md rules automatically. Local-first, zero upload,
  cryptographic hash chain. Zero code changes needed — installs as a
  background watcher.
version: 0.3.3
metadata:
  clawdbot:
    requires:
      bins:
        - python3
    install:
      - kind: uv
        package: k9audit-hook
    emoji: "🐕"
    homepage: https://github.com/liuhaotian2024-prog/K9Audit
    primaryEnv: ""
---

# K9Audit — Causal Audit for OpenClaw Agents

## When to Use This Skill

Use this skill when the user asks:
- "What did my agent do?" / "Why did my agent do that?"
- "Did any skill violate my rules?" / "Was my AGENTS.md respected?"
- "Show me violations" / "Audit my agent"
- "Trace why that happened" / "Find the root cause"
- "Set up K9Audit" / "Install the auditor"

Also activate when a skill behaves unexpectedly — offer to run
`k9log trace --last` to show the causal evidence chain.

---

## First-Time Setup (One Command)

Run this once to install K9Audit and start automatic monitoring:

```bash
bash {baseDir}/skills/k9audit/setup.sh
```

This script:
1. Installs `k9audit-hook` via pip
2. Registers a `gateway:startup` hook so monitoring restarts automatically
3. Starts the background watcher immediately — no gateway restart needed

After setup, **every OpenClaw tool call is automatically recorded**.
No code changes needed in any skill.

---

## How It Works

K9Audit runs a background watcher that monitors OpenClaw's session files:

```
~/.openclaw/agents/*/sessions/*.jsonl
```

Every time OpenClaw writes a `toolCall` entry, K9Audit:
1. Reads your `AGENTS.md` as the intent contract (Y\*_t)
2. Checks the tool call against your constraints
3. Writes a CIEU five-tuple to the tamper-proof ledger

**No PreToolUse hook needed. No code changes in skills. Zero friction.**

---

## Auditing Commands

After setup, use these commands to query the audit ledger:

```bash
k9log stats                              # violation summary
k9log verify-log                         # verify hash chain integrity
k9log trace --last                       # causal trace of last violation
k9log report --output audit_report.html  # full HTML report
```

---

## How Constraints Work

K9Audit automatically reads your existing `AGENTS.md` — no extra config needed.

**Example AGENTS.md (already works with K9Audit):**

```markdown
# My Agent Rules
- Never run rm -rf
- Do not modify .env files
- Never access /etc/ directory
- Only write to ./projects/
- Do not commit directly to main
- Only access api.github.com domain
```

K9Audit parses these rules and enforces them on every tool call.
Any violation is immediately recorded with the full causal chain.

---

## What Makes K9Audit Different

Every other tool records **what happened**.
K9Audit also records **what was supposed to happen** (Y\*_t intent contract).

The gap is the violation — causally traceable, cryptographically verifiable.

**Real verified case**: An agent read `CONSTRAINTS.md` — then attempted to
write the file that document declared off-limits, 10 seconds later.
A filesystem diff shows nothing. The CIEU chain shows exactly what the
agent saw before it acted.

Reproduce: `python k9_case002_replay.py` then `k9log verify-log`

---

## Watcher Management

```bash
# Check watcher status
k9log openclaw-watch status

# Stop watcher
k9log openclaw-watch stop

# Restart watcher
k9log openclaw-watch start
```

---

## Optional: Team Sync

K9Audit is local-first. Ledger stays on your machine by default.
For shared team dashboards:

```bash
k9log sync enable --endpoint https://your-server.com/api/ingest --api-key KEY
k9log sync push
```

---

## Links

- GitHub: https://github.com/liuhaotian2024-prog/K9Audit
- Install: `pip install k9audit-hook`
- License: AGPL-3.0 | US Provisional Patent 63/981,777

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

k9audit

Directory Structure

SKILL.md

Report

Notice