[WRITE][risk=medium] Assemble + hash-chain-seal an evidence bundle for a framework.

One-call happy path: coverage + approval trail + exceptions + sealed evidence records → a bundle .json under ~/.compliance-aiops/bundles/. Reads audit DBs and writes a local artifact only; touches no external system.

Args: framework: hipaa / pci_dss / soc2 / gdpr / iso27001 / djcp_l3. period_start / period_end: ISO timestamps bounding the reporting period. out_path: Where to write the bundle (default: the bundle dir). sign: If True and a signing key is stored, attach an HMAC signature. period: Convenience relative window (e.g. "7d", "last-7-days") used only when period_start / period_end are not supplied.

[READ] Ready-to-paste cron line + command for periodic sealed-bundle generation.

WRITES NOTHING and starts no daemon — it only composes and validates the crontab line and the exact non-interactive compliance-aiops bundle generate invocation (with the master-password env note) an operator can schedule.

Args: framework: hipaa / pci_dss / soc2 / gdpr / iso27001 / djcp_l3. cron: A standard 5-field cron expression (default: 02:00 every Monday). period: Relative window each run should cover (e.g. "7d", "last-7-days"). sign: If True, include --sign in the composed command.

[WRITE][risk=medium] Attach an HMAC signature over a bundle's seal (uses stored key).

Requires a signing key in the encrypted store ('compliance-aiops secret set signing-key'). Medium risk because it reads the encrypted secret store.

Args: bundle_path: Path to a bundle .json.

[WRITE][risk=medium] Render a bundle to markdown / csv / json / oscal.

"oscal" emits a NIST OSCAL 1.2.3 Assessment Results document (written as .oscal.json). Read oscal_assessment_results first if you need the document inline plus its limitations — notably that control ids are not resolved against an imported OSCAL catalog, and that OSCAL has no "partially satisfied" state for the controls this tool evidences only partially.

Args: bundle_path: Path to a bundle .json. fmt: "markdown", "csv", "json", or "oscal". out_path: Output path (default: alongside the bundle).

[READ] A sealed bundle as an OSCAL 1.2.3 Assessment Results document.

Returns the document inline (writing a file is export_bundle's job) with a summary and an explicit limitations list. Three things OSCAL cannot express are handled rather than hidden: import-ap points at a back-matter resource saying no assessment plan exists; control ids are framework-native and NOT resolved against an imported catalog; and because status has only satisfied/not-satisfied, controls this tool evidences only PARTIALLY are reported satisfied with an evidence-strength prop plus remarks naming what the audit trail does not prove — the count is in summary so it cannot be skimmed past.

UUIDs are deterministic (v5, derived from the bundle's chain head), so re-exporting the same bundle produces a byte-identical document.

Args: bundle_path: Path to a bundle .json (from list_bundles).

[READ] Previously generated bundles + their chain head and metadata.

[READ] Supported compliance frameworks (HIPAA / PCI-DSS / SOC 2 / GDPR) + control counts.

[READ] Per-control coverage for a framework over a period (are we covered?).

Args: framework: hipaa / pci_dss / soc2 / gdpr. since / until: ISO timestamps bounding the reporting period.

[READ] Evidence rows for ONE control + population size + reproducible query.

Args: framework: hipaa / pci_dss / soc2 / gdpr. control_id: e.g. "164.312(b)", "10.2", "CC8.1", "Art.30". since / until: ISO timestamps bounding the period. sample_size: Number of representative evidence rows to include.

populationSize is the full evidence count; sample is capped at sample_size and sets truncated when there was more. scanTruncated reports whether the underlying event scan itself hit its cap — if it is true, the population is a slice and no coverage claim should be made from it.

[READ] Controls with no/weak evidence, each with an honest reason + remediation.

States the design-vs-operating caveat: audit trails evidence operating effectiveness strongly and control design/configuration only partially.

Args: framework: hipaa / pci_dss / soc2 / gdpr. since / until: ISO timestamps bounding the period.

[READ] List sibling audit DBs (~/.-aiops/audit.db) + readability/row counts.

Call this first to see which governed AIops tools' trails are available as compliance evidence.

[READ] Cross-tool audit event query — the workhorse.

Args: source: Restrict to one source tool (e.g. nutanix-aiops). skill / tool / status / risk_level: Field filters. approved: True = only ops with an approver; False = only ops without one. selector: Evidence class filter — audit_trail / attribution / change / enforcement / exception. since / until: ISO timestamps bounding the period. limit: Max rows to return.

Returns {"events": [...], "count": N, "returned": N, "limit": L, "truncated": bool}. When truncated is true more events matched than were returned — narrow the filters or raise the limit. Never characterise the trail (counts, "no violations found") from a truncated result.

[READ] Op counts bucketed by hour/day — monitoring-continuity evidence.

Args: since / until: ISO timestamps bounding the period. bucket: "hour" or "day".

[READ] Chain head for a source's current events + row-id gap detection.

Record the returned chainHead out-of-band; re-run later to detect changes. Row-id gaps may indicate deleted audit rows.

Args: source: Source tool name (from list_audit_sources). since / until: ISO timestamps bounding the range.

[READ] Verify a sealed evidence bundle: chain integrity, seal head, signature.

Args: bundle_path: Path to a bundle .json produced by generate_evidence_bundle.

[READ] High-risk write ops with approver + rationale (the change-approval trail).

The who/what/when/why/approval artifact for SOC 2 CC8.1, PCI 7-8, HIPAA §312(a).

Args: since / until: ISO timestamps bounding the period. high_only: True = only high/critical-risk writes (default); False = all writes.

[READ] Denied / error / budget-exceeded ops — enforcement + anomaly evidence.

Denials prove the governance controls actually block, not rubber-stamp.

Args: since / until: ISO timestamps bounding the period.

[READ] List recorded, not-yet-applied undo tokens (most recent first).

Each entry names the original tool, the inverse tool that undo_apply would run, and a human note. Use the undoId with undo_apply.

Returns {"undos": [...], "returned": N, "limit": L, "truncated": bool}. truncated is measured (one extra row is fetched), not guessed from a length coincidence: when it is true there are MORE tokens than shown, so re-run with a higher limit rather than reporting the list as complete.

Each entry carries effectVerified. False means the original write lost its response, so the change it reverses is PROBABLE, not confirmed — check the live state before applying, and do not report the result as a restore of a state that may never have been reached.

Args: limit: Max rows to return (default 50, capped at 500). target: Unused (undo state is host-local); accepted for CLI uniformity.

[WRITE][risk=medium] Apply a recorded undo by dispatching its inverse tool.

The inverse runs through its own governed tool, so its real risk tier is recorded there. Pass dry_run=True to preview the inverse call without executing it. A token can only be applied once.

Args: undo_id: The undoId from undo_list (or an _undo_id in a write result). dry_run: If True, preview the inverse tool + params without running it. target: Passed through to the inverse tool when it accepts a target.