audit

Documentation

Index

• func Disable()
• func Log(e Entry)
• type BrokenEntry
• type Entry
• type VerifyResult
  • func Verify(path string) (VerifyResult, error)
  • func (r VerifyResult) Ok() bool

Functions

func Disable

func Disable()

Disable is a test-only kill switch; production opts out by leaving $CTXCOP_AUDIT_LOG unset.

func Log

func Log(e Entry)

Log writes a chained JSON-line entry iff $CTXCOP_AUDIT_LOG is set. Off by default — a security tool shouldn't silently retain detection records next to the secrets that triggered them. Best-effort; errors swallowed so a logging failure can't block a hook call.

Each entry's Prev is the previous entry's Hash, forming a chain detectable by `ctxcop audit verify`. After a legacy (unchained) entry, the next chained entry restarts the chain from "".

Types

type BrokenEntry

type BrokenEntry struct {
	Line   int
	Kind   string // "parse" | "hash" | "chain"
	Detail string
}

BrokenEntry locates and labels a single integrity failure.

type Entry

type Entry struct {
	TS     string   `json:"ts"`
	Tool   string   `json:"tool"`
	Action string   `json:"action"`
	Rules  []string `json:"rules,omitempty"`
	Count  int      `json:"count,omitempty"`
	Field  string   `json:"field,omitempty"`
	Prev   string   `json:"prev"`
	Hash   string   `json:"hash"`
}

Entry is one detection event. Narrow on purpose — for "did ctxcop see something interesting", not for forensics rich enough to re-create the secret. Prev + Hash form a tamper-evident chain across appends; see docs/verify-reproducibility.md's sibling, ctxcop audit verify.

type VerifyResult

type VerifyResult struct {
	File         string
	TotalEntries int
	Verified     int
	Legacy       int
	Broken       []BrokenEntry
}

VerifyResult summarizes an audit-log verification pass.

func Verify

func Verify(path string) (VerifyResult, error)

Verify walks the audit log, recomputes each entry's hash, and checks each Prev points at the prior entry's Hash. Legacy entries (no Hash — from pre-chain ctxcop versions) are counted and treated as a chain reset for the next chained entry.

func (VerifyResult) Ok

func (r VerifyResult) Ok() bool

Ok reports whether the chain (and every entry's own hash) verified cleanly. Legacy entries don't fail Ok — they're surfaced separately.