How Sovra builds, checks and ships its own software

This page lists the controls that exist in the Sovra repository today, in the order of the pipeline, each with a way to check it yourself. A control appears here only while the file that implements it still says so; the page is re-evaluated against those files on every request.

Verify the evidence bundleDependenciesBuildChecks on every changeRelease and deploySigned releasesReporting a vulnerability

Verify the evidence bundle

Every file these controls are read from is published, signed, at /trust/evidence/. Download them, check the signature, then run the command under each control. No access to the Sovra source repository is needed.

This bundle belongs to release 0.31.4. File list with SHA-256

curl -fsSO https://sovra.informatologia.pt/trust/evidence/{SHA256SUMS,SHA256SUMS.sig,allowed_signers,Dockerfile,dependabot.yml,docker-compose.reuse.yml,docker-compose.yml,dockerignore,pyproject.toml,secrets.baseline,sovra-0.31.4.cdx.json,uv.lock,workflow-deploy.yml,workflow-tests.yml}
ssh-keygen -Y verify -f allowed_signers -I release@sovra.informatologia.pt -n sovra-release -s SHA256SUMS.sig < SHA256SUMS
sha256sum -c --ignore-missing SHA256SUMS

Run in the directory where you downloaded the bundle. allowed_signers is the trust anchor: it is not covered by SHA256SUMS, so you rely on this site's TLS for it.

Dependencies

What goes into the build, and how it is pinned.
01

Every package in the lock file uv.lock is pinned to an exact version and carries a SHA-256 hash for each file.

How to check
grep -c 'hash = "sha256:' uv.lock
grep -c '{ url = ' uv.lock   # same number
02

Third-party packages install from the lock, as prebuilt wheels only. Source distributions are refused (no-build), so no package build script runs during the image build.

How to check
grep -n 'no-build' pyproject.toml
grep -n 'uv sync' Dockerfile
03

Dependency resolution ignores any file uploaded inside a cooldown window (exclude-newer), so a freshly published malicious release is not picked up on day one.

How to check
grep -n 'exclude-newer' pyproject.toml
04

Dependabot proposes updates weekly for GitHub Actions, Docker images and Python packages, with the same cooldown. Each update goes through the same checks as any other change.

How to check
cat dependabot.yml

Build

How the build and the container are put together.
05

Every GitHub Action used in the workflows is pinned to a full commit SHA, not to a movable tag.

How to check
grep -hn 'uses:' workflow-*.yml
06

Every workflow sets read-only repository permissions (contents: read) by default. The only write permission anywhere is contents: write in the signing job, which attaches the signed files to the release.

How to check
grep -n -A1 '^permissions:' workflow-*.yml
grep -n ': write' workflow-*.yml   # one line: contents: write in the sign job
07

Every base image in the Dockerfile, including the uv installer image, is pinned by its SHA-256 digest.

How to check
grep -n '^FROM' Dockerfile
08

The container runs as an unprivileged user. The application directory is owned by root and read-only to that user; only the data volume is writable.

How to check
grep -n '^USER\|adduser\|chown' Dockerfile
09

In the reference deployment files the application container has a read-only root filesystem.

How to check
grep -n 'read_only' docker-compose*.yml
10

In the reference deployment files the application container drops all Linux capabilities and sets no-new-privileges.

How to check
grep -n -A2 'cap_drop\|no-new-privileges' docker-compose*.yml

Checks on every change

What runs automatically on every change.
11

The checks below run on every pull request and on every push to main.

How to check
sed -n '/^on:/,/^permissions:/p' workflow-tests.yml
12

pip-audit checks the exported lock file, with hashes required, against known vulnerabilities.

How to check
grep -n 'pip-audit' workflow-tests.yml
13

Sovra scans its own dependency files with its own engine and publishes the resulting CycloneDX SBOM as a build artifact.

How to check
grep -n 'selfscan\|upload-artifact' workflow-tests.yml
ls sovra-*.cdx.json   # the SBOM of this release, in the bundle
14

The pip-audit and self-scan job also runs every night, so a newly published advisory shows up without a commit.

How to check
grep -n -A1 'schedule:' workflow-tests.yml
15

Semgrep (python and security-audit rulesets) scans the source, and any finding fails the build.

How to check
grep -n 'semgrep' workflow-tests.yml
16

Ruff runs with the flake8-bandit security rules (S) enabled, on top of its correctness rules.

How to check
grep -n -A2 '^\[tool.ruff.lint\]' pyproject.toml
grep -n 'ruff check' workflow-tests.yml
17

detect-secrets scans every tracked file against an audited baseline, so a committed secret fails the build.

How to check
grep -n 'detect-secrets' workflow-tests.yml
ls -l secrets.baseline
18

The workflow files themselves are checked with actionlint and zizmor.

How to check
grep -n 'actionlint\|zizmor' workflow-tests.yml
19

The test run fails if line coverage drops below 80%. The floor lives in pyproject.toml, so it applies to everyone, not only to CI.

How to check
grep -n 'fail_under' pyproject.toml
grep -n -- '--cov' workflow-tests.yml

Release and deploy

What has to be true before code reaches production.
20

Production deploys start only when a GitHub release is published. Nothing deploys on a push, a merge or a manual dispatch.

How to check
sed -n '/^on:/,/^permissions:/p' workflow-deploy.yml
21

The release tag must point at a commit that is already on main. Code that was never merged is not deployed.

How to check
grep -n 'is-ancestor' workflow-deploy.yml
22

The release tag must equal v plus the version the code reports (sovra.__version__).

How to check
grep -n 'TAG' workflow-deploy.yml
23

Pre-releases never deploy.

How to check
grep -n 'prerelease' workflow-deploy.yml
24

The full test suite, with the coverage floor, runs at the release commit. The deploy job waits for it and ships exactly that commit.

How to check
grep -n 'needs:\|pytest\|--ref' workflow-deploy.yml
25

The deploy job waits for the signing job, which builds the release files, signs them and verifies the published copies. An unsigned or unverifiable release does not deploy.

How to check
grep -n 'needs:\|release_sign\|release_verify' workflow-deploy.yml

Signed releases

Release files carry a signature you can verify yourself.
26

Release files are listed in a SHA256SUMS file, which is signed with an SSH key in the sovra-release namespace. The public key is published below.

How to check
curl -fsS https://sovra.informatologia.pt/.well-known/sovra-release-signing.pub -o allowed_signers
ssh-keygen -Y verify -f allowed_signers -I release@sovra.informatologia.pt -n sovra-release -s SHA256SUMS.sig < SHA256SUMS
sha256sum -c --ignore-missing SHA256SUMS

Public key (allowed_signers)

Reporting a vulnerability

Send vulnerability reports to info@informatologia.pt (mailto). Machine-readable contact: /.well-known/security.txt