sepinetam/mcp-for-stata/stata-audit

Stata-MCP Audit

Read Stata-MCP evidence without changing the source JSONL ledgers or snapshot objects. Resolve every script and template relative to this skill directory, while resolving the default evidence root from the user's current working directory as <cwd>/.statamcp.

Choose the Narrowest Script

Use the user's project directory as the command working directory. Example:

python /absolute/path/to/stata-audit/scripts/validate_audit.py .statamcp

All scripts accept an optional artifact-root argument and default to ./.statamcp. The text output is suitable for a quick review; add --json when structured downstream analysis is useful.

Review Rules

• Join lifecycle records with exact run_id, not filename or time proximity.
• Treat event == "blocked" with executed == false as a prevented call. A

normal blocked call is security evidence, not a script failure.

• Follow security_event_ids to audit/security.jsonl and report missing or

inconsistent links.

• Verify snapshot bytes against the complete recorded SHA-256. The first eight

characters are display-only.

• Treat missing terminal events as investigation leads, not proof that a tool

executed or failed.

• Treat client name and version as self-reported metadata, not verified user or

agent identity.

• Keep full paths masked unless the user explicitly needs them. The reporting

scripts support --show-paths for that case.

• Never edit, sort, truncate, rotate, replay, or repair evidence in place.

Script Usage

Security review:

python scripts/security_audit.py .statamcp
python scripts/security_audit.py .statamcp --json

Project usage analysis:

python scripts/analyze_audit.py .statamcp

Inspect the latest records or reconstruct one exact run:

python scripts/inspect_audit.py .statamcp --limit 20
python scripts/inspect_audit.py .statamcp --run-id <exact-run-id> --json

Validate evidence:

python scripts/validate_audit.py .statamcp

Exit code 0 means no integrity error was found. Exit code 1 means the evidence is missing, malformed, inconsistent, or failed a snapshot hash check. Warnings remain visible but do not alone fail validation.

Render the combined dashboard or one tool view:

python scripts/render_audit_html.py .statamcp
python scripts/render_audit_html.py .statamcp --tool stata_do

The default output directory is:

<cwd>/.statamcp/reports/html/

Combined reports use YYYYMMDD-HHMM-audit.html. A filtered report uses the tool name, for example YYYYMMDD-HHMM-stata_do.html. The renderer locates assets/audit_dashboard.html from its own Python-file location, so it works regardless of the user's current directory.

The dashboard derives its global start and end from the minimum and maximum timestamps in the selected evidence. Its two Time position handles start at those exact boundaries and control the visible chart start and end. Ordinary text uses Times New Roman; tool names, run IDs, ledgers, hashes, and paths use a monospace code font. Times are displayed as YYYY-MM-DD HH-MM with the viewer's local time-zone name and UTC offset.

After rendering, report the exact generated path and ask whether the user wants to open it. Open it only after the user agrees. Use the platform's normal local file opener (open on macOS, xdg-open on Linux, or start on Windows).

Reporting Boundaries

State conclusions as measurements from recorded tool calls. Do not claim that the audit captures unrecorded thinking, manual Stata actions, authorship, or a continuous agent session. If evidence has parse errors, unsupported schema versions, unmatched lifecycle events, missing security links, or failed hashes, surface those limitations before summarizing behavior.