Docs › Self-Hosted Server

Enterprise

Self-hosted server

Run a live, access-controlled multi-repo PullGuard dashboard inside your own boundary, on your own domain (e.g. https://pullguard.yourcompany.com) — with history, SSO and RBAC.

How it works — and why it's safe

PullGuard's core promise is that your code never leaves your runners. A vendor-hosted dashboard would break that, so instead you run the server:

• Your CI scans your code (exactly as today) and POSTs the results only — findings, scores, grades — never source code.
• The server stores history in a local database and renders the dashboard.
• PullGuard never sees your data, and the server makes no call home: the Enterprise licence validates locally (offline key), so it runs fully air-gapped.

This is separate from the PullGuard licensing service — that only validates subscriptions and never receives scan data.

Prerequisites

• An active Enterprise licence (the server refuses to start below Enterprise).
• Docker (compose or Kubernetes/Helm) or Node 22+ to run it directly.
• A TLS-terminating reverse proxy in front (the server speaks plain HTTP behind your proxy).

Configuration

The server is configured entirely with environment variables:

The server fails closed: it won't start without a valid Enterprise licence and at least one ingest token — and, if SSO is enabled, not without a valid SSO configuration.

Getting the image

The server image is a private, Enterprise-only artifact, available two ways — use whichever fits your network policy.

Option A — private registry pull (ghcr.io/pullguard-dev/pullguard-server). With your Enterprise licence you receive a registry read token — authenticate once, then pull normally:

echo "$PULLGUARD_REGISTRY_TOKEN" | docker login ghcr.io -u pullguard-customer --password-stdin
docker pull ghcr.io/pullguard-dev/pullguard-server:latest

Option B — licence-gated HTTPS download. No GitHub identity or registry egress required — the same licence key you already hold (online pg_live_* token or offline pullguard_enterprise_* key) authenticates a direct tarball download:

curl -fL -H "Authorization: Bearer $PULLGUARD_LICENSE_KEY" \
  -o pullguard-server.tar \
  "https://pullguard.dev/api/server-image?version=latest"

# verify against the sha256 returned in the x-pullguard-sha256 response header
sha256sum pullguard-server.tar

docker load -i pullguard-server.tar

version accepts latest or an exact server semver (e.g. 0.4.1 — the server has its own version line, see below). Revocation is the licence itself — expire or revoke the key and the download stops; the endpoint never receives or stores scan data. Rate-limited per source IP.

Pin a version tag for change-controlled environments. Every published server image carries SLSA build provenance and an SBOM — verify with docker buildx imagetools inspect (Option A) or the sha256sum check above (Option B) before first run, exactly as with the scanner image.

Air-gapped? Either option produces a local image: mirror Option A on a connected machine (docker pull → docker save → transfer → docker load), or use Option B directly — the offline licence key validates locally, so the running server never contacts a registry or PullGuard. Don't have your registry token yet? Contact us with your licence org.

Image versions and tag channels

The server ships on its own version line, separate from the scanner — server releases are 0.x.y while the scanner is 1.x.y. Three tag channels are published for every server release:

Pin, don’t float. The docker pull and ?version=latest commands above use latest because it is the shortest thing to paste for a first evaluation. For anything you run for real, replace it with the minor line (:0.4) or a digest — the same guidance as the scanner image.

For the current server version and what changed in it, see the release notes; server releases are called out there alongside the scanner. Your licence covers every version on the line you are entitled to — upgrading is a re-pull plus a restart, and the database is migrated in place on first boot.

Quick start (Docker Compose)

export PULLGUARD_LICENSE_KEY=pullguard_enterprise_yourorg_...
export PULLGUARD_SERVER_INGEST_TOKENS=$(openssl rand -hex 24)

docker compose up -d
# dashboard on http://localhost:8080  (put your TLS-terminating proxy in front)

A Dockerfile, docker-compose.yml, and a Helm chart ship with the server package. For Kubernetes, create a docker-registry pull secret from your registry token (imagePullSecrets in the chart values), store the licence and ingest tokens as a secret, and helm install the chart.

Wire your CI to upload results

Add two inputs to your PullGuard GitHub Action — after each scan it uploads the results to your server (best-effort; a server hiccup never fails your build):

- uses: pullguard-dev/pullguard-action@v1
  with:
    server-url: https://pullguard.yourcompany.com
    server-token: ${{ secrets.PULLGUARD_SERVER_TOKEN }}

Set PULLGUARD_SERVER_TOKEN to one of your ingest tokens. The Action uploads only the finding report — never source.

The dashboards

• Portfolio / org view (/) — every repo at a glance: project count, failing repos, open-findings and critical/major totals, plus a sortable table. Click a row to drill in.
• Single-repo view (/repos/<org>/<name>) — grade, score, findings over time, with drill-down to file:line.

These reuse the same renderers as the air-gapped HTML report — see Reports & Dashboard.

Triage & governance — with an immutable audit trail

Disposition findings per finding, per line from the dashboard: mark a finding Acknowledged, False positive, Won’t fix, or Accept risk (until a date), with a reason. The buttons are inline on every finding row — on the repo dashboard and on the triage view — and each one is labelled with the decision it records, so it is always clear what is being asserted. The triage view is a full review surface — a “% triaged” KPI, per-finding effort and estimated cost, code owner (from git-blame), and faceted filters by severity, category and status.

• Tamper-evident audit trail. Every decision — who dispositioned which finding, when, from which status to which, with the comment — is appended to a hash-chained log an admin can read and export. Auditors get a verifiable record; a decision cannot be altered or removed undetectably.
• Role-gated & CSRF-protected. With SSO enabled, triage actions require an authenticated session with the maintainer role (or above); viewers see dispositions but can’t change them. Deployments without an identity provider can opt in to triage with PULLGUARD_SERVER_OPEN_TRIAGE=true (v1.5.1) — decisions stay audit-logged (recorded as unauthenticated), and the server refuses to start if the flag is combined with SSO.
• Annotates, never deletes. A triaged finding is dispositioned in the dashboard and history — it is not removed from the underlying record, so nothing is silently dropped.
• Accepted risk expires. An accepted risk carries a review date (1–365 days) and a required reason. When the date passes the acceptance stops applying on its own: the finding reads as active again with an “expired on” note, it stops counting as triaged, and it stops being sent to CI. A time box you have to remember to enforce is not a time box.
• Resolved & reopened, tracked automatically. When a finding stops appearing in a scan it is recorded as resolved; if it comes back it is recorded as reopened. The dashboard shows both as headline counts, a per-scan “fixed” badge in the scan history, and a “resolved in this scan” strip — so remediation work is visible, and a regression is visible as a regression. Nothing is deleted to do it: the original scans and findings are untouched. On a noisy pipeline, PULLGUARD_SERVER_RESOLVE_AFTER_SCANS requires several consecutive clean scans before anything counts as fixed.
• Viewers see the controls, disabled. A reviewer without the maintainer role still sees every action button, greyed out, with a one-line reason and a sign-in link — never a blank space that could be mistaken for a missing feature.
• Decisions can reach CI (opt-in). With server.pullTriage: true in a repo’s .driftrc.yml, a scan fetches that repo’s decisions at start and honours them — so a false positive dismissed on the dashboard stops blocking the merge, without anyone editing a file twice. It is off by default, it only activates when the server URL and token are already configured, and a committed .pullguardignore entry always wins. Security findings keep their protection: a dismissal that would hide one is refused, and a reasoned false-positive override stays fully visible — it only lifts the block. If the server is unreachable the scan simply proceeds with no decisions applied and says so.

This is distinct from scanner-side .pullguardignore (which suppresses a finding on future scans, and never for security-category findings). Triage is the review/governance layer on the results you already have.

Settings — keep the portfolio meaningful

Settings writes need an admin session or a managed token carrying admin + agent-write. Without single sign-on there are no sessions, so bootstrap the first credential from the host that owns the data directory — pullguard-server token mint --label "bootstrap admin" --scopes "your-org/*" --admin — printed once, never stored, expiry bounded, audit-logged; then mint narrower tokens with it and revoke it.

A Settings area (linked from the portfolio header) lists every repository the server holds, with a Hide / Unhide toggle and a short note. Hiding a decommissioned, archived or experimental repository keeps it out of the portfolio your leadership team reads — without losing anything.

• Nothing is deleted. A hidden repository keeps every scan, finding, triage decision and audit row. Its scans keep uploading, its own dashboard stays reachable by direct link (with a banner saying it is hidden), and an administrator can un-hide it at any time.
• Never a gate input. Visibility is a display choice. It has no effect on a Quality Gate verdict, on the merge decision, or on anything a scan reports — hiding a repository can never hide risk.
• Administrator only, always. Changes require an authenticated admin session and are written to the same tamper-evident audit log as a triage decision. Unlike triage, there is no unauthenticated mode: removing a repository from the org view always carries an identity.
• Everyone else sees it read-only. Viewers and maintainers see the page with the controls disabled and a one-line reason.

Query API — embed PullGuard in your own UI

A read-only JSON API lets you surface repo grades, security posture, compliance status, finding trends and triage state inside your own control-plane / ops UI — without leaving the tools your team already uses.

• GET /api/v1/portfolio — all repos + roll-up.
• GET /api/v1/repos/<id>/scans — per-repo scan history.
• GET /api/v1/repos/<id>/scans/<scanId>/findings — findings, each with its triageStatus.
• GET /api/v1/repos/<id>/triage — that repo’s live decisions (this is what a CI scan reads when server.pullTriage is on). Authorized by the same per-repo scopes as ingestion — a token can only read the repositories it is scoped for.
• GET /api/v1/health — reachability.

Authenticated with a read-only token (PULLGUARD_SERVER_READ_TOKENS, GET-scoped — it cannot mutate data) and an explicit CORS allowlist (PULLGUARD_SERVER_CORS_ORIGINS; no wildcard). Results only — never source.

The contract is served by the server

GET /api/v1/openapi.json returns an OpenAPI 3.1 description of every operation — parameters, response shapes, status codes and which credential each one accepts. It is generated from the routes the server actually registered, so it cannot describe an endpoint that does not exist, nor omit one that does. Point any client generator at it. The document is public and unauthenticated because it contains no repository, no finding, no credential and no operator name.

Stability: /api/v1 is additive-only. We may add endpoints, optional query parameters and response fields; we will not remove or rename a field, change its type, change a status code, or tighten validation on a request that is accepted today. A breaking change would ship on a new path (/api/v2/…) with /api/v1 still served, so your integration upgrades on its own schedule.

Which credential, and what it can reach

An environment read token (PULLGUARD_SERVER_READ_TOKENS) is the bootstrap path: unscoped, no expiry, changed by a deploy. A managed token issued in Settings → Tokens is always scoped to named repositories, always carries an expiry of 1–365 days, and can be rotated or revoked in one click. Prefer the managed, scoped kind: listings are filtered to its scope, a request for a repository outside it is refused and audited, and a leak is worth less. Some reads refuse an unscoped token outright — /api/v1/repos/<repo>/triage returns your team’s decisions, so it is authorized by scope rather than by holding any accepted token.

CORS is an exact-origin allowlist (PULLGUARD_SERVER_CORS_ORIGINS) — no wildcard, no origin reflection. Rate limits apply only to failed authentication, per IP, so a healthy integration is never throttled. Paging is a clamped limit with a pre-cap total: an over-large limit returns the cap rather than an error, and there is no cursor, so one call can never walk an entire estate.

BASE=https://pullguard.internal
AUTH="Authorization: Bearer $TOKEN"

curl -s -H "$AUTH" $BASE/api/v1/whoami
curl -s -H "$AUTH" $BASE/api/v1/portfolio
curl -s -H "$AUTH" "$BASE/api/v1/repos/acme%2Fweb/scans?limit=20"
curl -s -H "$AUTH" "$BASE/api/v1/repos/acme%2Fweb/scans/scan_42/findings?severity=critical"
curl -s -H "$AUTH" $BASE/api/v1/repos/acme%2Fweb/gate-status
curl -s -H "$AUTH" "$BASE/api/v1/repos/acme%2Fweb/diff?format=csv" -o diff.csv
curl -s -H "$AUTH" $BASE/api/v1/repos/acme%2Fweb/triage
curl -s $BASE/api/v1/openapi.json > pullguard-api.json

Agent access — opt-in, and off by default

A coding agent connected through pullguard mcp --server reads findings out of the box. It can also be allowed to act — but only if an administrator ticks two boxes on the Tokens page for that specific credential: agent write (record triage decisions within the token’s scope) and, on top of it, admin (hide a repository, set gate and SLA policy, issue or revoke tokens).

• Off for everything that already exists. Every token issued before this feature, and every token issued without ticking the box, has neither capability.
• Not merely refused — not offered. When a capability is off, the agent is never told the corresponding tools exist, so a prompt-injected caller cannot even ask for one.
• Each action confirmed and attributed. Every write must be confirmed explicitly on the call itself, and lands in the tamper-evident audit log as agent:<client> alongside the administrator who granted the access.
• Withdrawal is one click. It takes effect on the next request and does not require rotating a secret every runner holds. Granting or withdrawing agent access is itself the one operation an agent credential can never perform.
• Security findings are untouched. They can never be blind-suppressed, a false-positive override still needs a reason and stays visible everywhere, and a class decision can never name an always-surfaced security type.

API tokens — issue, rotate and revoke without a deploy

Every credential your CI presents used to live in an environment variable, so issuing one to a new team was a deploy and revoking one was an emergency deploy. Settings → Tokens (/settings/tokens) lets an administrator do both from the dashboard.

• The secret is never stored. Only a SHA-256 hash of it is kept, so the plaintext exists once — on screen, at creation — and cannot be recovered afterwards. If it is lost, rotate; there is nothing to look up.
• Every token expires. A lifetime of 1–365 days is required. There is no way to issue an immortal credential.
• Every token is scoped. A token names the repositories it may reach (org/repo or org/*) and can act on nothing else — for uploads and for reads. There is no unscoped managed token.
• Rotation has a grace window. Rotating issues a new secret and leaves the old one working for a bounded period (default one hour, maximum 24, zero for an immediate cutover) so runners can be updated without an outage. The replacement inherits the original expiry — rotating a secret does not re-authorize the credential.
• Revocation is immediate and auditable. Issue, rotate and revoke are each written to the same hash-chained audit log as a triage decision, recording the label, the scopes and the expiry — never the secret.
• Environment tokens keep working. They are the bootstrap path: a server with an empty database still has to accept its first upload. Use PULLGUARD_SERVER_INGEST_TOKEN_SCOPES for those, and manage the rest here.

Per-repository policy & SLA — with relaxations in the open

The Settings page also carries two per-repository controls, both administrator-only and both audited.

• Quality-gate policy. Each repository inherits an organisation default (PULLGUARD_SERVER_POLICY_BLOCK_AT, default major, and PULLGUARD_SERVER_POLICY_WARN_AT, default moderate) and an administrator can override the pair for one repository. Every change appends a versioned history row — who changed it, when, from what — readable by any signed-in viewer. Gate conditions include finding-severity floors, security and AI-surface counts, score and grade, and (server 0.4.2+) partial_scan_max, which refuses a scan that hit a file cap — a report without coverage data counts as partial.
• A relaxation is never silent. A repository whose policy blocks less than the organisation default is badged RELAXED on its own dashboard, naming who set it and what it was relaxed from, and is listed on the portfolio your leadership team reads. Lowering a bar is a decision the next reader can question.
• SLA budgets. Per-severity ageing budgets in days (defaults: critical 7, major 30, moderate 90), overridable per repository. The dashboard shows an “over SLA” count and the oldest open finding, the triage view gains an age column and an over-SLA filter, and the query API returns ageDays, ageBucket and overSla on every finding.
• SLA is display only. An ageing number is never an input to a gate or a merge decision. A metric that can block a merge gives a team a reason not to record the honest first-seen date, and the entire value of the number is that it is honest.

What changed — scan-to-scan diff

/repos/<org>/<name>/diff answers the Monday-morning question directly: what appeared, what was fixed, what came back, what changed severity, and which triage decisions were recorded between any two scans (defaulting to the previous one and the latest). The actionable rows carry the same labelled triage buttons, and the whole comparison exports as JSON or CSV.

“Came back” comes from the server’s own cross-scan record, so a regression is reported as a regression rather than as a new finding. Nothing about a diff is stored — it is derived from the scans you already have, so it can never disagree with them.

Working at scale — hundreds of repositories

• A searchable repository switcher sits in the header of every page: type any part of an org/name, results are grouped by organisation and keyboard-navigable, and the repository you are looking at is pinned at the top. It works without JavaScript (the panel always contains a plain link to the portfolio), and it carries names only — no grades or counts — so a page never leaks the shape of a project to someone who cannot open it.
• The portfolio table filters as you type, can group by organisation, and paginates at 100 rows, so a 250-repository estate renders immediately. The existing CSV/JSON export is still the way to take the whole thing away.
• Class triage decisions. A legacy area carrying hundreds of instances of one accepted judgement can be dispositioned once — a finding type plus a path glob, with a required reason and an optional review date — and renders as a single collapsed row that expands to everything it covers. It can never name an always-surfaced security finding, because a blanket rule also covers the next one nobody has seen yet; those are always dispositioned individually. Class decisions reach CI through the same opt-in pull as per-finding ones, and are never an input to a Quality Gate.
• Bulk triage. Select several findings and record one decision for all of them. Every key is re-validated server-side and each one binds its own evidence, so a bulk decision is a delivery convenience and never a shortcut past a check.

Operating it — probes, proxies and the audit anchor

• Liveness: GET /healthz. It answers as long as the process is up and deliberately does not touch the database — a liveness probe that depends on a working query turns a degraded server into a restart loop.
• Readiness: GET /readyz. It runs a real transaction against the store (proving it is writable and migrated) and re-checks the licence expiry, so an instance that stops being writable or entitled is pulled out of rotation with a 503 instead of quietly serving failures. Both probes are rate-limited and return a constant body — no version, no paths, nothing an unauthenticated caller can learn from.
• Behind your proxy: terminate TLS at your own reverse proxy and set PULLGUARD_SERVER_BASE_URL to the external URL (required when SSO is enabled — it is what the IdP redirects back to). Every response carries Cache-Control: no-store, X-Content-Type-Options: nosniff, Referrer-Policy: no-referrer, X-Frame-Options: DENY and a per-request nonce-based Content-Security-Policy, so the dashboard cannot be framed, cached by a shared proxy, or made to run an injected script.
• Tamper evidence that outlives the database: point PULLGUARD_SERVER_AUDIT_ANCHOR_FILE at a path outside the data volume. The audit chain and its counters otherwise live in the same file they protect. Then pullguard-server audit verify re-hashes the whole chain against that external witness and exits non-zero if anything has been altered or removed — a command an operator can run on a stopped server, or from cron.
• Turning surfaces off: PULLGUARD_SERVER_QUERY_API=false hard-disables the read-only API even when ingest tokens exist; PULLGUARD_SERVER_ENFORCE_REPO_BAND=true makes the licensed repository band a hard reject on a new repository rather than a warning.

Endpoint reference

Every route the server exposes. A build-time check fails if one ships without a row here.

Assignment — who is working on this

Every finding carries an Owner column with two facts side by side: the git-blame author the scan recorded, and the person or team it is assigned to. An assignee is user:<sso-subject> or team:<idp-group> — the prefix is required, because a subject and a group are both opaque strings from the same directory, and guessing would silently route a finding to a group nobody is in.

An assignment is routing, and nothing else. It never suppresses a finding, never changes a severity, is never a filter that removes a row from a machine-readable surface, and is never an input to a Quality Gate. That is precisely why it is allowed on deployments where a merge-blocking decision is not. Every assignment is recorded in the same tamper-evident audit chain as a triage decision.

The owner suggestion is pre-filled, never applied. It comes from the scan itself — git blame, or the CODEOWNERS owner the scanner resolved when you opted in. This server has no repository access and never reads a CODEOWNERS file: if the scan did not carry ownership, there is no suggestion. Blame names whoever last touched the line, which after a reformat is a stranger, so a human presses the button.

Notifications are off. Assignment sends nothing unless you have alerts configured and subscribe a destination to the assigned trigger. /me is your worklist across every repository you can see.

Teams — per-team repository visibility

A 400-repository portfolio is unreadable to the team who owns eight of them. Settings → Teams scopes an identity-provider group to a set of repositories — the same group strings your role map is already keyed on, so there is no membership list here to go stale.

• Reading narrows. A member of a scoped team sees only those repositories in the portfolio, the switcher, the Query API and their worklist. A direct link still resolves, exactly as it does for a hidden repository — this is curation, not access control.
• Writing is refused. Once any team is scoped, a triage decision or an assignment outside the writer’s scope is refused. A filter that narrowed the listing but left the write reachable would be decorative: the repository is one URL away, and a decision recorded there changes a merge verdict.
• Nobody is locked out by somebody else’s configuration. A person in no scoped team sees everything, exactly as before. Scoping one team must never blank the dashboard for the rest of the organisation.

Administrators are never scoped — they configure the scopes. Every change is audited.

Retention and backup — the operator owns the disk

The default is keep everything, and an upgrade changes nothing. Retention is opt-in per repository. It deletes stored scan payloads beyond the window you set — and it may never delete the latest scan of a repository, a triage decision, a first-seen date, an assignment, or an audit row. A dry-run count is shown before you commit, and recorded in the audit chain alongside the policy that produced it, so the decision and its blast radius are one record.

The backup action writes a complete, consistent copy of the database — taken with SQLite’s VACUUM INTO, because a plain file copy of a live database is torn — into the directory you configured, with a sidecar carrying its checksum and the audit chain’s row count and head hash. After a restore, pullguard-server audit verify checks the chain against that sidecar: a self-consistent chain proves only that the copy is coherent, and a tampered copy is coherent too.

There is no download route, and there will not be one. The file is every finding, decision, actor and audit row on the deployment. An endpoint that returned it would make one stolen administrator session equal to the whole dataset in a single request.

Share links — signed, expiring, read-only

The person who has to see a result is often not somebody you will provision an SSO seat for: an external auditor, a client’s security reviewer, a board member reading one quarter. The alternatives are a screenshot (unverifiable, and now a document nobody can revoke) or an account for a one-off read.

Off by default, behind two separate deployment-time acts. A maintainer mints a link for one report page of one repository, with a lifetime between an hour and thirty days.

• HMAC-signed over the exact scope — page, repository, scan, expiry — and verified in constant time. Flip one byte and the link is refused.
• Only the hash is stored, so a read of the database yields no usable link, and the URL is shown once and cannot be recovered from any page.
• Revocable independently of its expiry: “I sent that to the wrong address” needs an answer that is not “wait thirty days”.
• Never for a hidden repository, the audit log, or any settings surface.
• Minting, revocation and use are audited — the use record is the only evidence that anybody outside your organisation opened the page. It records that the link was used, never who or from where.

The shared page renders read-only: no triage or settings controls, no repository switcher, no API links, no navigation out of it, a banner naming the expiry, and search-engine noindex headers. A shared diff withholds triage actors — “who dismissed this” names an employee to a reader outside the organisation, and the audit log answers that question, under its own guard, to somebody inside it.

Alerts — tell the right people, without becoming a way in

PullGuard posts nowhere by default. Outbound alerts stay off until an administrator adds a destination in Settings → Alerts, and a destination cannot be added at all until you have named the hosts this server is allowed to reach.

A destination is a Slack, Microsoft Teams or plain-JSON webhook, scoped to one repository, an organisation, or all of them, and subscribed to the events you care about: a new critical security finding, a finding going over its SLA budget, a finding reopening, the quality gate flipping between pass and fail, or a new class triage decision. Every one of those is a change rather than a state, so a long-standing problem does not re-announce itself on every upload and train your team to mute the channel.

An alert carries the repository, the finding type, its severity, file:line and a link back to your dashboard — never source code, and never a finding’s message. It lands in a chat room whose membership PullGuard does not control, so it carries only enough to let somebody who is authorised go and look. Every body is signed HMAC-SHA256 with a per-destination secret, so your receiver can prove an alert came from your server and not from anyone who learned the URL.

An outbound feature on a security scanner is a way into your network if it is built carelessly, so this one is deliberately narrow:

• Allowlisted hosts only, and exact ones. No allowlist means the feature refuses to enable. A suffix rule for example.com would also admit evil-example.com, so you name the host you mean.
• HTTPS only, and redirects are never followed. A 30x is a delivery failure — following one would let the destination send your server anywhere.
• No private, loopback or link-local addresses unless you opt in for an internal chat server. The address is checked at connect time, so DNS cannot answer differently between the check and the socket.
• The signing secret is encrypted at rest with a key held outside the database, and can never be read back from the page. An alert that cannot be signed is not sent.
• Delivery never delays an upload. It is queued: a receiver that is down cannot slow a CI scan, let alone fail one. Three attempts with backoff, then the alert lands in a visible dead-letter queue with the reason — because an alert that was never delivered means somebody was supposed to be told and was not.
• Every destination change, test send and failed delivery is in the audit log.

The audit log, as a page — and a read-only role for it

Every triage decision, policy change, credential issuance, login and failed alert delivery is appended to one hash-chained log. GET /audit is that log as a page: filter by who, what, which repository and when; export the filtered set as CSV or JSON; and read the chain’s integrity in plain words at the top — whether the hashes verify, whether rows appear to be missing, and whether an external anchor is configured. Actors that are coding agents are badged, so an agent is never mistaken for a person. Nothing on the page can change the log.

Because it cannot write, it is the one privileged surface that can safely be given to a read-only auditor role: read the dashboards and the audit log, export evidence, and nothing else. It sits sideways on the ladder rather than above maintainer — a maintainer does not gain the audit log by being a maintainer, and an auditor never satisfies a write guard anywhere on the server. Map an IdP group to it exactly as with the others.

Compliance evidence pack — the quarter, in one file

An auditor rarely asks what your scanner finds today. They ask what you knew during the period, what you decided, who decided it, and whether the record has been edited since. Export a pack for one repository or the whole portfolio, over any date range, as a self-contained HTML document that opens with no network access — or as JSON for your GRC tool.

Each pack holds, per repository: the compliance framework rollups recorded on the scans in that period — the worst as well as the end-of-period one, because a control that failed for two months and passed on the last day did not have a passing quarter — every per-finding and class decision with its reason, actor and expiry, resolved and reopened counts with mean time to resolve, the quality-gate verdict history, an extract of the audit log, the versions in use, and the chain verdict at the moment of export.

Two things it deliberately is not. It is evidence supporting an assessment, never a compliance claim — a scanner can show a record, it cannot certify a control, and the pack says so on its first page. And it never re-assesses anything: this server holds no analysis engine, so every status in the pack is one your scanner emitted at the time and this server stored. Taking a copy is itself recorded in the audit log. No source code is included.

Human login — SSO & RBAC

By default (PULLGUARD_SSO_MODE=none) the dashboard is protected by your network boundary / reverse proxy, and machine ingestion is always token-authenticated. To require human login and role-gating, enable OIDC or SAML 2.0:

• OIDC — set PULLGUARD_SSO_MODE=oidc plus your issuer, client ID and secret, and the server's base URL (Authorization-Code + PKCE).
• SAML 2.0 — set PULLGUARD_SSO_MODE=saml plus your IdP metadata / certificate and entity IDs. Login is SP-initiated; an unsolicited assertion is refused. From server 0.4.2, PULLGUARD_SAML_UNSOLICITED_REDIRECT=true (default off) answers the identity provider's launcher tile with a single redirect into a normal login instead of an error — the assertion is never parsed or used, the redirect target is fixed, and the refused attempt stays in the audit log.
• RBAC — map IdP groups to roles (viewer < maintainer < admin, plus the read-only auditor) via PULLGUARD_SSO_ROLE_MAP. Access is deny-by-default: an authenticated user matching no role gets none.

Sessions are server-side with idle and absolute expiry and CSRF protection. Full SSO setup ships as docs/sso.md in the server package.

Security posture

• Results-only ingestion. The endpoint validates the report shape and rejects any source-looking payload; oversize bodies are refused (413).
• Token-authenticated machine ingestion (constant-time comparison).
• Fails closed — no start without a valid Enterprise licence + ingest token (+ SSO config when enabled).
• No call home — offline licence validation; runs fully air-gapped.
• Ships as a non-root container; the database is the system of record and stays on your volume.

Repository-band licensing

Since v1.4.0, Enterprise license keys can carry a signed repository-count band, and the server meters distinct-repo ingestion against it:

• Advisory by default — ingesting beyond the band produces a clear warning; nothing breaks.
• Opt-in hard enforcement — enable it to have the server refuse ingestion for repos beyond the band.
• Existing keys are unaffected — a key without a band remains unlimited.

The band is part of the signed key, so it validates locally like the rest of the licence — still no call home, still fully air-gapped.

Questions or an Enterprise trial? hello@pullguard.dev.