Skip to content

Csf Audit

csf_audit - SQLite-backed persistence for CSF safety decisions.

Cluster: Uncategorised | Type: component | MCP Tools: 9

Overview

Durable, hash-chained, tamper-evident SQLite audit trail for every CSF (Computational Safety Framework) safety decision. Records each verdict immediately and links rows with a prev_hash/row_hash sha256 chain. verify_chain() recomputes the whole chain and returns structured evidence (ok, first_broken_row, reason, chain_length, head_hash); a small additive csf_audit_chain_anchor table (chain length + head hash) lets it also catch tail-deletes and unauthorized appends that the row-by-row link check alone would miss. Async Lean results patch records via patch_lean() (the one mutation that re-chains so the patched fields stay hash-covered). Provides compliance queries against the audit trail. Exposed read-only on the AIBlock and MCP surfaces, which promote the verdict verbatim.

Production scope

CsfAuditLog is suitable for local MCP installs, first-user workflows, and design-partner pilots where an inspectable SQLite audit trail is enough. It is not yet an enterprise-grade audit backend: records are not encrypted at rest, retention and rotation are deployment-owned, and SQLite's single-writer model is not appropriate for high-throughput multi-tenant deployments. For regulated, paid team, or enterprise deployments, pair it with external secret management, backups, retention policy, monitoring, and a durable central audit/log sink.

When to use:

  • Persisting a complete tamper-evident log of all CSF safety verdicts
  • Querying historical safety decisions for compliance audits
  • Patching records with Lean formal proof confirmations after async verification

Example:

from mvp.csf_audit import CsfAuditLog

with CsfAuditLog(db_path="csf_audit.db") as log:
    audit_id = log.record(
        report,
        action="file_write",
        tier="DESTRUCTIVE",
        verdict="HITL_REQUIRED",
    )
    log.patch_lean(audit_id, verified=True, error="")
    records = log.query(tier="DESTRUCTIVE", limit=100)
    assert log.verify_chain()["ok"]  # verify_integrity() is the boolean compat wrapper

Works well with: csf, csf_gate, formal_methods

Public API

CsfAuditLog

Constructor:

Parameter Type Default
db_path str ''

Methods:

close() -> None

record(report: SafetyDecisionReport, action: str, tier: str, verdict: str, risks: list[dict] | None = None, z3_verified: bool | None = None, delta: float | None = None) -> str

patch_lean(audit_id: str, verified: bool | None, error: str) -> bool

query(tier: str | None = None, verdict: str | None = None, since: str | None = None, limit: int = 100) -> list[dict]

report_md(audit_id: str) -> str

verify_integrity() -> bool

Return True when the append-only hash chain is internally consistent.

verify_chain() -> dict[str, Any]

Recompute the audit hash chain and return structured integrity evidence.

CsfAuditInput(BaseModel)

Field Type Default
op str required
parameters dict[str, Any] Field(default_factory=dict)
production_mode bool False
run_mode str 'beta'
reviewer_signature str ''
deployment_profile str ''

CsfAuditOutput(BaseModel)

Field Type Default
op str ''
result dict[str, Any] Field(default_factory=dict)
message str ''
agentic_evidence dict[str, Any] Field(default_factory=dict)
completion_state str 'qualified-draft'
reliability_label str 'qualified-draft'
warning_card dict[str, Any] \| None None
evidence list[dict[str, Any]] Field(default_factory=list)
request_id str ''
task_id str ''
run_id str ''
code str ''
degraded bool False
degradation_reason str ''

CsfAuditBlock(AIBlock)

AIBlock wrapper for the CSF audit log (SQLite-backed safety decision persistence).

Constructor:

Parameter Type Default
planner Any \| None None

Methods:

infer(input: CsfAuditInput) -> Result[CsfAuditOutput]

MCP Tools

Operation Source
ops csf_audit_mcp
help csf_audit_mcp
log csf_audit_mcp
query csf_audit_mcp
verify_chain csf_audit_mcp
get_info csf_audit_mcp
list_strategies csf_audit_mcp
explain_record_decision csf_audit_mcp
describe_capabilities csf_audit_mcp