# SARIF Output

Census generates [SARIF v2.1.0](https://docs.oasis-open.org/sarif/sarif/v2.1.0/) (Static Analysis Results Interchange Format) reports from comparison results. SARIF is the industry standard for security tool output and integrates with GitHub Code Scanning, Defect Dojo, Azure DevOps, and other security platforms.

## Basic usage

```bash
# Print SARIF to stdout
census compare /suspect --format sarif

# Save to file
census compare /suspect --format sarif --output report.sarif

# CI pipeline: scan and upload to GitHub Code Scanning
census compare /suspect --format sarif --output results.sarif --exit-zero
gh api repos/{owner}/{repo}/code-scanning/sarifs -f sarif=@results.sarif
```

## SARIF structure

Each match produces a SARIF `result` entry:

```json
{
  "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
  "version": "2.1.0",
  "runs": [{
    "tool": {
      "driver": {
        "name": "certisigma-census",
        "version": "1.3.0",
        "rules": [{
          "id": "CENSUS001",
          "name": "ExfiltratedFile",
          "shortDescription": { "text": "File matches attested inventory" },
          "help": {
            "text": "A suspect file's SHA-256 matches...",
            "markdown": "**Exfiltrated file detected**..."
          },
          "properties": {
            "tags": ["security", "data-exfiltration", "file-integrity"]
          }
        }]
      }
    },
    "invocations": [{ "executionSuccessful": true }],
    "results": [...]
  }]
}
```

### Key fields per result

| Field | Content |
|-------|---------|
| `ruleId` | `CENSUS001` |
| `level` | `error` |
| `message.text` | Describes the match with hash, attestation ID, and level |
| `locations[0].physicalLocation.artifactLocation.uri` | `file:///` URI of the suspect file (percent-encoded) |
| `properties.attestation_id` | CertiSigma attestation ID |
| `properties.level` | Certification tier (`T0`, `T1`, `T2`) |

## CI/CD integration

### GitHub Code Scanning

```yaml
- name: Census breach detection
  run: |
    census compare ./artifacts --format sarif --output census.sarif --exit-zero
- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: census.sarif
```

### Report-only mode

Use `--exit-zero` to prevent pipeline failure while still generating the SARIF report:

```bash
census compare /suspect --format sarif --output report.sarif --exit-zero
```

### Summary mode

Combine `--summary` with SARIF to get concise CI logs while the full SARIF file captures all details:

```bash
census compare /suspect --format sarif --output report.sarif --summary --exit-zero
```

## Error handling

If the SARIF file cannot be written, Census reports the error on **stderr** and exits with code 1. Stdout remains clean for pipeline parsing.

## URI encoding

File paths in SARIF `artifactLocation.uri` are percent-encoded per RFC 3986, ensuring correct parsing by SARIF consumers regardless of special characters in filenames.
