compliance-aiops

Compliance AIops

Disclaimer: Community-maintained open-source project, not affiliated with, endorsed by, or sponsored by any framework body or GRC vendor. HIPAA, PCI-DSS, SOC 2, GDPR and OSCAL are referenced descriptively; trademarks belong to their owners. Source at github.com/AIops-tools/Compliance-AIops under the MIT license.

Governed compliance-evidence tooling — 19 MCP tools. It reads the audit trails your governed AIops agents already write (~/.-aiops/audit.db, one shared audit_log schema, discovered via ~/.*-aiops/audit.db) read-only, and turns that activity into framework-mapped, hash-chain-sealed compliance evidence. It does not scan infrastructure and does not replace a GRC platform.

Standalone: the governance harness is bundled (compliance_aiops.governance). Not a platform wrapper — no external API, no network, no platform credentials. Evidence, not certification; fully offline and deterministic.

What This Skill Does

Frameworks & sample controls

Audit trails prove operating effectiveness strongly but control design / configuration only partially — each control is labelled strong or partial, and gap_analysis surfaces the caveat rather than overclaiming.

Quick Install

uv tool install compliance-aiops
compliance-aiops init       # discover sibling ~/.*-aiops/audit.db, set org name, optional signing key
compliance-aiops doctor     # which sibling audit DBs are present/readable

When to Use This Skill

• Map AI-agent infra-ops activity to a framework's controls (coverage_summary)
• Pull the evidence rows + population for one control (control_evidence)
• Find controls with no or weak evidence, with the honest caveat (gap_analysis)
• Produce a change-approval artifact — who approved which high-risk write and why (approval_report)
• Produce enforcement / anomaly evidence — denied / errored / budget-tripped ops (exceptions_report)
• Seal a tamper-evident evidence bundle (generate_evidence_bundle, sign_bundle) and later prove it wasn't altered (verify_bundle)
• Detect deleted / missing audit rows in a source trail (verify_source_chain)

Do NOT use to scan or operate infrastructure, or as a GRC platform. It reads the audit DBs the other AIops-tools write; for platform operations use those other AIops-tools.

Related Skills — Skill Routing

Common Workflows

1. "The SOC 2 auditor wants Q3 change-approval evidence by Friday"

1. compliance-aiops doctor → confirm the source audit trails are discoverable and readable before you promise a delivery date
2. compliance-aiops report sources (MCP: list_audit_sources) → which sibling audit trails were found, and the event count and date range in each. If a source you expected is missing, the bundle would be silently incomplete — fix discovery first
3. compliance-aiops report coverage soc2 → confirm CC8.1 is actually covered by the evidence you have, before generating anything
4. compliance-aiops report approvals → the high-risk write operations with their named approver and rationale — this is the population CC8.1 is asking about
5. compliance-aiops bundle generate soc2 --since 2026-07-01 --until 2026-10-01 --sign → a hash-chain-sealed bundle under ~/.compliance-aiops/bundles/
6. compliance-aiops bundle export --format markdown → the auditor-facing report (also json / csv)
7. Failure branch: if report coverage shows CC8.1 thin, do not generate anyway and hope — run workflow 2 first and hand the auditor the honest gap statement. A bundle asserts what the audit trail contains; it cannot manufacture evidence that was never recorded.

2. "Which controls are we actually short on?" (gap analysis)

1. compliance-aiops report sources → establish the evidence base and its date coverage; a gap caused by a missing source is a different problem from a gap caused by missing activity
2. compliance-aiops report gaps hipaa (also pci_dss, soc2, gdpr) → controls with no or weak evidence, each with an honest caveat and a remediation suggestion
3. compliance-aiops report exceptions → the operations that ran without an approver or rationale — usually the fastest-to-fix category of gap
4. Drill into one control's population with control_evidence (MCP) to see the reproducible query behind the coverage number, so the figure can be defended rather than merely quoted
5. compliance-aiops report coverage again after remediation to confirm the gap actually closed
6. Failure branch: if list_frameworks does not carry the framework or control the auditor named, say so — this tool maps to HIPAA / PCI-DSS / SOC 2 / GDPR and does not silently substitute a near-miss control.

3. Prove a delivered bundle was not altered

1. compliance-aiops bundle list → locate the bundle and its recorded chainHead
2. compliance-aiops bundle verify → re-derives the hash chain, compares it to the seal's chainHead, and checks the optional signature
3. Because the chain is computed over evidence records only, the same (framework, period, sources) reproduces the same chainHead — regenerate and compare to prove reproducibility
4. Record the chainHead out-of-band (ticket, email to the auditor, WORM store) at delivery time; that out-of-band copy is what makes later verification meaningful
5. verify_source_chain (MCP) on each source → returns the source chain head and flags row-id gaps, a sign that rows were deleted from that audit.db
6. Failure branch: a chainHead mismatch or a row-id gap means the evidence is not trustworthy — escalate, and treat the source audit.db as the system of record. Do not re-seal a fresh bundle to make the mismatch go away; the tool is tamper-evident, not tamper-proof, and its whole value is that it reports this rather than papering over it.

4. 定期封存 — schedule periodic sealed bundles (no daemon)

This tool ships no scheduler; it emits a cron line for you to install.

1. compliance-aiops report sources → confirm the sources you want sealed are discoverable from the account cron will run as (a common failure: cron sees a different $HOME)
2. compliance-aiops bundle schedule soc2 --cron "0 2 * * 1" --period 7d --sign (MCP: bundle_schedule_hint) → returns a cronLine plus the exact non-interactive command. It writes nothing.
3. Paste the cronLine into crontab -e, e.g. 0 2 * * 1 compliance-aiops bundle generate soc2 --period 7d --sign
4. Export COMPLIANCE_AIOPS_MASTER_PASSWORD in the cron environment so the signing key unlocks non-interactively — never inline the real password in the crontab
5. After the first scheduled run, compliance-aiops bundle list and bundle verify the newest bundle to confirm the unattended path really works
6. Failure branch: if the cron run produces no bundle, the usual causes are an unset master password (signing cannot unlock) or COMPLIANCE_AIOPS_HOME not being set in cron's environment, so sources resolve elsewhere. Verify by running the emitted command by hand with a clean environment before trusting the schedule.

Governance & Safety

The skill reads audit trails and writes evidence bundles and records what it does; it does not decide whether producing or signing a bundle is permitted. That is your agent's judgement, or the filesystem permissions of the account it runs as. There is no read-only switch, policy file, or approval gate.

• Audit is the guarantee, and it is not bypassable. Every operation — MCP and CLI alike — is logged to ~/.compliance-aiops/audit.db (relocatable via COMPLIANCE_AIOPS_HOME): params, result, status, duration, and the risk tier. The CLI writes the same row the MCP path does.
• The source audit trails are opened read-only; the tool never mutates them. The only files written are bundles under ~/.compliance-aiops/bundles/.
• COMPLIANCE_AUDIT_APPROVED_BY / COMPLIANCE_AUDIT_RATIONALE are optional annotations recorded on the audit row (who/why); they are never required and never block.
• Tamper-EVIDENT, not tamper-PROOF — the source audit.db remains the system of record.

References

• references/capabilities.md — full tool → inputs → returns reference
• references/cli-reference.md — CLI command reference
• references/setup-guide.md — source discovery, org name, optional signing key, integrity notes