All tutorials

GitHub Actions, from one step to a full workflow

Cordon 0.7.07 sections · 2 diagramsView this tutorial on GitHub

Level 2, every repository's pipeline. The Cordon action installs the scanner (checked against the hash pinned in the action), scans, writes SARIF for code scanning and a summary for the job, and fails the job on your gate. Each step below adds to the one before; copy whichever level you need into .github/workflows/cordon.yml.

GitHub Actions, from one step to a full workflow, figure 1
┌──────────────────────────────────────────────────────────────────────────┐
│  pull request / push                                                     │
│      │                                                                   │
│      ▼                                                                   │
│  install cordon-scanner ── checked against the action's pinned hash      │
│      │                                                                   │
│      ▼                                                                   │
│  scan ──► job summary ──► SARIF ──► Security tab, findings on the lines  │
│      │                                                                   │
│      ├── dependency review (pull requests): what the lockfile change adds│
│      │                                                                   │
│      ▼                                                                   │
│  exit 0 pass · 1 findings at fail-on · 2/3 error · 4 incomplete          │
└──────────────────────────────────────────────────────────────────────────┘
name: cordonon: [push, pull_request]permissions:  contents: read           # checkout  security-events: write   # SARIF upload to code scanningjobs:  scan:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v4      - uses: Threx-code/cordon/[email protected]

The defaults are the safe ones: fail-on: high, fail-on-incomplete: true (a scan that could not read everything has not passed), sarif: true, and secret evidence hashed. The action refuses to run under pull_request_target, which hands a writable token and the repository's secrets to a job that may check out untrusted code.

permissions:  contents: read  security-events: write  pull-requests: write     # only for the commentjobs:  scan:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v4      - uses: Threx-code/cordon/[email protected]        with:          dependency-review: "true"           # added · upgraded · downgraded · removed          dependency-review-online: "true"    # fetch, verify and compare each changed release          dependency-review-comment: "true"   # one comment, updated on every push
GitHub Actions, from one step to a full workflow, figure 2
   pull request bumps the lockfile
        │
        ├─► scan        the whole tree; the gate
        └─► review      the graph at the base commit vs this branch
                         known malicious or high/critical ─► job fails
                         with --online: new install hooks, capabilities,
                         binaries and a new publisher, release by release

The base commit is fetched by its id and passed through the environment, never written into a script, because a branch name is chosen by whoever opens the pull request. Tutorial 21 explains the review in full.

name: cordonon:  pull_request:  push:    branches: [main]  schedule:    - cron: "17 3 * * *"     # nightly: new advisories against code nobody touchedpermissions:  contents: read  security-events: writejobs:  gate:    if: github.event_name != 'schedule'    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v4      - uses: Threx-code/cordon/[email protected]        with:          fail-on: high          dependency-review: "true"  nightly:    if: github.event_name == 'schedule'    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v4      - uses: Threx-code/cordon/[email protected]        id: cordon        continue-on-error: true      # makes the backlog visible without blocking anyone        with:          fail-on: medium      - if: steps.cordon.outputs.findings != '0'        run: echo "::warning::${{ steps.cordon.outputs.findings }} findings at medium or above"
Wherefail-onWhy
Pull requesthighthe gate that holds the line
Push to mainhighthe same gate after merge
Nightlymedium, non-blockingan advisory published today, against code unchanged for a month
Releasehigh, fail-on-incomplete: "true"the one place a partial scan must never pass
  release-gate:    runs-on: ubuntu-latest    permissions:      contents: read      security-events: write    steps:      - uses: actions/checkout@v4      - uses: Threx-code/cordon/[email protected]        with:          verify-install: "true"      # the wheel's PyPI provenance, signed by Cordon's release                                      # workflow, and every installed file against it          fail-on: high          fail-on-incomplete: "true"          policy: .github/cordon-policy.yaml   # the organisation's ceiling (tutorial 39)
permissions:  contents: read  security-events: write  id-token: write              # the job's own OIDC identity; no secret is storedsteps:  - uses: actions/checkout@v4  - uses: Threx-code/cordon/[email protected]    with:      upload: "true"      cloud-url: https://core-api.cordonscan.com   # a fixed value, never from github.event

The job exchanges its OIDC token for a fifteen-minute Cordon token. An organisation admin adds a trust rule for the repository first. A scan of the default branch can close findings that are fixed.

InputDefaultWhat it does
target.path or archive to scan
working-directory.where to run
configdiscoveredthe repository's cordon.yaml
policynonean organisation policy: a ceiling the repository cannot lower
severitylowreport findings at or above
fail-onhighfail the job at or above
fail-on-incompletetruea scan that did not read everything fails
sarif / sarif-filetrue / cordon.sarifcode scanning upload
evidencemaskednone, masked or hash_only; secrets are always hashed
dependency-reviewfalsethe pull request's dependency changes
dependency-review-onlinefalsefetch and compare each changed release
dependency-review-commentfalsepost the review as a comment
verify-installfalsecheck the scanner against its signed release
upload / cloud-urlfalsesend results to Cordon Cloud

Outputs: findings (how many met the gate), sarif-file, and complete.

A tag can be moved; a commit cannot. Pin the action by its full commit id with the version as a comment; the ci/github/cordon-pin-bump.yml workflow (tutorial 24) keeps it current with a pull request per new release:

      - uses: Threx-code/cordon/action@<40-character commit id>   # v0.7.0

Next: 36 · GitLab CI.