# Upload code scanning results

Run any scanner that writes SARIF in a workflow and show its findings under Security → Code scanning.

Code scanning shows the results of any tool that writes SARIF 2.1.0, such as Semgrep, CodeQL or
Trivy, run in your workflows. It is opt-in: nothing is scanned until you upload. SARIF files may be
up to 12 MB.

## Prerequisites

- A role or access key with `git:UploadCodeScanningResults` on the repository. From a workflow,
  the role's trust policy must admit the repository, and the job needs
  `permissions: id-token: write`.
- Reading alerts needs `git:ListSecurityAlerts`; dismissing one `git:UpdateSecurityAlert`.

## Upload from a workflow

With Semgrep's open-source rules, replace repo-id with the repository's id and
role-rn with the RN of a role that has `git:UploadCodeScanningResults`:

```yaml
# .github/workflows/code-scanning.yml
on:
  push: { branches: [main] }
  pull_request:
permissions: { id-token: write, contents: read }
jobs:
  semgrep:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pipx run semgrep scan --config p/default --sarif --output semgrep.sarif || true
      - uses: ews/configure-credentials@v1
        with: { role-to-assume: role-rn }
      - name: Upload results
        run: |
          REF="${GITHUB_REF}"
          [ "${GITHUB_EVENT_NAME}" = pull_request ] && REF="refs/pull/${{ github.event.number }}/head"
          jq -n --rawfile s semgrep.sarif --arg sha "${{ github.event.pull_request.head.sha || github.sha }}" --arg ref "$REF" \
            '{commitSha: $sha, ref: $ref, sarif: $s}' |
          curl -sf -X POST "$DCLOUD_API_URL/git/api/repositories/repo-id/code-scanning/sarifs" \
            -H "Authorization: EWS-ACCESS-KEY $DCLOUD_ACCESS_KEY" -H 'Content-Type: application/json' --data-binary @-
```

In a workflow that runs on Deutsche Cloud CI, the job's `github.token` may upload SARIF for its own
repository, so
`github/codeql-action/upload-sarif` works unchanged; see [GitHub Actions](/docs/github-actions).

## Upload by hand

**CLI**
```sh
dcloud git security upload-sarif 5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60 \
  --commit-sha 9fceb02d0ae598e95dc970b74767f19372d61af8 --ref refs/heads/main \
  --sarif "$(cat semgrep.sarif)"
```

**API**
```http
POST /git/api/repositories/5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60/code-scanning/sarifs
{ "commitSha": "9fceb02d0ae598e95dc970b74767f19372d61af8", "ref": "refs/heads/main", "sarif": "{\"version\":\"2.1.0\",\"runs\":[]}" }
```

## Result

- An upload for the default branch updates **Security → Code scanning** and marks alerts the tool
  no longer reports as fixed.
- An upload for a pull request's head (`refs/pull/<n>/head`) is listed for that commit
  (`GET …/commits/{sha}/code-scanning`).
- Severity follows GitHub: a rule's `security-severity` score when it has one (≥ 9 critical, ≥ 7
  high, ≥ 4 medium), otherwise the SARIF level.
- On **Security → Code scanning**, an alert's actions dismiss it (**Dismiss: risk is
  tolerable**, **Dismiss: not used**, **Dismiss: false positive**) or **Reopen** it.

An upload is refused with 400 `sarif is not JSON` or `Not a SARIF 2.1.0 document: …`, and with
404 `No such commit in this repository` when `commitSha` (the full 40-character id) is not a
commit of the repository. `ref` must be a full ref such as `refs/heads/main`.

## Related

- [Repository security features](security-features.md)
- `git.security.upload-sarif` · `dcloud git security upload-sarif`
