Compliance Reports
CodeStax compliance reports are point-in-time evidence of what one stored PR review evaluated and decided. They can support an audit trail, vendor assessment, or control test, but they are not a certification and do not, by themselves, prove that a repository, application, or organization complies with a framework.
Accessing Reports
Navigate to Dashboard → Reviews → Compliance. Export access follows the same organization and review-read authorization boundary as the underlying review.
What the Evidence Captures
The JSON report records the evidence available for that review. Top-level fields identify the review and timing, source and target branches, provider, change statistics, processing status, risk summary, and implementation-pattern score. The implementation-pattern score is a reviewer aid that summarizes risky implementation signals; it is not an authorship probability.
Its nested assessment object is the authoritative structured assessment and includes:
- The immutable gate fields:
immutable_gate_decision(passed,failed, orinconclusive),immutable_gate_passed,immutable_gate_reasons, andimmutable_gate_snapshot_version - The non-sensitive
immutable_policysnapshot used by that gate:risk_threshold,max_critical_issues,max_high_issues,observed_critical_issues, andobserved_high_issues; this is not a copy of raw mutable organization settings or secrets analysis_health,scan_health,coverage_complete, the structuredcoveragemanifest,excluded_files, and recordedomissionsprovider_delivery_stateandprovider_delivery_completed_at, which record whether and when publication of the completed review result reached a terminal state at the source-control provider
The top-level issues list includes active and suppressed findings, suggestions, suppression state and reason, and the available per-finding provenance: fingerprint, source, source_engine, rule_id, confidence, model_id, model_revision, prompt_version, analysis_run_id, and evidence_version.
Older or partially migrated reviews may not contain every provenance or snapshot field. A missing value remains missing in the report; it must not be inferred from the current policy, a later review, or a different provider delivery.
Reading the Outcome
| Outcome | Meaning |
|---|---|
| Passed | The immutable gate passed and the captured analysis evidence is clean and complete within the recorded analysis scope. |
| Failed | The captured policy thresholds were exceeded with complete evidence. |
| Inconclusive | Evidence is incomplete, degraded, missing, inconsistent, or unverified, so no pass/fail conclusion is supported. |
A completed processing status is not the same as complete evidence. An inconclusive or degraded report is evidence of incomplete analysis, never proof of compliance or proof that the change passed. A low numeric risk score is diagnostic only when health or coverage is incomplete.
Provider delivery is also a separate fact from analysis. A review can finish analysis while publication of its summary, status, or inline comments fails or remains pending. Use the captured delivery state when demonstrating that a result reached the provider.
Some exports expose an audit_ready field. It means that the report met CodeStax’s evidence-completeness checks for that review; it is not a compliance opinion and does not establish that any external control operated effectively.
Export Formats
| Format | Contract and best use |
|---|---|
| JSON | The richest structured evidence package. It retains the nested assessment, including the gate snapshot version, scan health, full coverage manifest, exclusions, omissions, evidence-completeness reasons, provider-delivery completion time, and available per-finding provenance. Use it for archival, programmatic validation, or GRC ingestion. |
| CSV | A flattened, row-per-finding view; a review with no findings still produces one review-level row. It repeats the gate decision/pass/reasons, policy limits and observed counts, analysis health, coverage status/evidence, omissions, provider-delivery state, suppression data, and provenance columns. It does not preserve every nested JSON field, including the gate snapshot version, scan health, dedicated exclusions list, or provider-delivery completion time. |
| HTML | A reduced, browser-readable summary for teams that need editable or web-native output. It is not the complete structured evidence package. |
A professionally paginated, human-readable report with the immutable gate outcome, captured policy, health and coverage, omissions, prioritized findings, and provenance notes. It is returned as a genuine application/pdf download. Retain JSON alongside it when the complete machine-readable evidence package is required. |
Do not treat the formats as interchangeable. A reduced CSV, HTML, or PDF view does not imply that evidence omitted from that view was verified. Retain JSON with the human-readable artifact when the full machine-readable record is required.
Using Reports in a Control Assessment
Reports can support evidence that a change was reviewed, a captured gate decision was made, exceptions were retained, and provider delivery was attempted or completed. Framework mappings-for example SOC 2, ISO 27001, OWASP, or PCI DSS-describe possible control relevance only. They do not prove framework coverage, control design, operating effectiveness, remediation, or compliance.
The control owner or auditor must still determine:
- Whether the reviewed repositories, branches, time period, and sampling are in scope
- Whether analysis coverage and health are sufficient for the control objective
- Whether the captured policy was approved and appropriate at the time of the review
- Whether failed, suppressed, or omitted findings were authorized and remediated
- Whether provider-delivery evidence and branch protection show the decision was enforced
- What independent evidence is required by the applicable control or framework
For a defensible evidence package, retain the report with policy approvals and change history, source-provider/branch-protection records, remediation or exception approvals, deployment records, and any independent control evidence. The export does not replace an auditor’s or control owner’s assessment.
API Access
Export a review through the authenticated review API:
GET /api/reviews/{review_id}/export?format=json
GET /api/reviews/{review_id}/export?format=csv
GET /api/reviews/{review_id}/export?format=html
GET /api/reviews/{review_id}/export?format=pdfThe requester must have review-read access to the review’s organization. The endpoint does not broaden tenant access or bypass the review authorization boundary.