Skip to main content

Registry access log

The audit log records administrative actions. The registry access log records something else: every request a client makes to your organisation’s package and container registry. That covers each download, each metadata read (an npm packument, a PyPI simple index, a Maven maven-metadata.xml), each upload and each delete, and it includes requests that a policy blocked. Nothing is sampled, with two exceptions for routine CI traffic through the dependency proxy. Both apply only to a request a Forgejo Actions job made, that the proxy allowed and answered without an error:

  • CI metadata reads are not recorded (since 2026-10-12). A package index or version list (an npm packument, a PyPI simple index, a Maven maven-metadata.xml) read by a job is not stored. One package install makes hundreds of these reads, and they say nothing the download after them does not.
  • CI downloads served from the proxy cache are counted, not logged one by one (since 2026-10-13). When a job downloads a package file that the proxy already holds, the download is added to the pull census instead of being stored as an event: one count per UTC day, package version and repository, with the ids of the Actions runs that pulled it. So you can still see which version of which package entered which build, by run, from the census.

Everything else is still one event, CI included:

  • every download the proxy fetched from the upstream registry (a cache miss), and every download from your own registry
  • every request a policy refused, blocked or would have blocked
  • every request that failed (a status of 400 or more)
  • every request made by a person, a bot, a registry robot or anonymously, metadata reads and cache hits included

A CI download that is counted in the census keeps the package, version, day, repository and run, and the number of pulls. It does not keep what an event holds beyond that: the file name, the size, the exact time of each pull (the census has the first and last of the day), the client address, the user agent and the request id. It is not delivered to a SIEM endpoint and is not in access-log.ndjson; it is in the census API and in metadata/pulled-versions.ndjson in the data export. Events stored before these dates are kept for their normal retention.

What an event holds

FieldMeaning
occurred_atWhen fremforge answered the request (UTC).
originWhich component saw the request: registry for the package registry. The dependency proxy writes proxy.
surfaceapi (/api/packages/…), oci (/v2/…, the container registry) or web (a file downloaded from the web UI).
org, package.type, package.name, package.version, package.fileWhat was asked for.
repoFor a request made with a Forgejo Actions job token: the job’s repository, <owner>/<repo>. Empty otherwise.
actionsFor a request made with a Forgejo Actions job token: the run it came from, {repo_id, run_id, run_number, job_id}. run_number is the run’s page, /<owner>/<repo>/actions/runs/<run_number>; run_id is GITHUB_RUN_ID. null for any other request, and for requests recorded before 2026-10-08.
package.digestsha256:<hex> of the file or manifest that was served or stored, when the registry named it.
actiondownload, metadata, upload, delete or other.
actorWho the registry authenticated: {type: "user" | "bot" | "anonymous", id, login}. A token or a session resolves to the user it belongs to, and Forgejo Actions jobs show as a bot.
client_ipThe client address as fremforge’s edge saw it. It is empty when fremforge could not verify the address, for example on a request that did not come through the edge.
user_agentThe client’s User-Agent, cut at 256 characters.
http.method, http.status, http.bytesThe request method, the answer, and the size where it is known. Size is unknown for a download that is redirected to object storage. A HEAD request appears as GET, because the CDN forwards HEAD requests to the registry as GET.
decision, decision_reasonallowed; blocked; would_block (a policy running in shadow mode, or your image-scan block action warn, would have refused it, and the request went through); or pending_refused (your package policy refuses files whose scan has not finished yet, and this file’s had not; the client got 503 with Retry-After, and a retry once the scan finishes succeeds). decision_reason names the rule that decided, for example malware, image_malware, image_cve, registry_scan:<reason> or immutable_retired (see immutable package versions).

Never recorded: an access token, an Authorization header, a cookie or a query string. A presigned storage URL, for example, never appears in an event.

Reading it

With a token that carries audit:read:

curl -sS -H "Authorization: Bearer $FFP_TOKEN" \
  "https://frem.sh/_app/api/v1/orgs/acme/access-log?action=download&type=npm&since=2026-10-01"

Results come newest first. Pass the next value of a page as cursor to get the next page, and stop when next is null. The cursor is a keyset, so events that arrive while you page never shift or repeat a row. Filters: since, until, origin, action, decision, type, name, version, actor (a login, or anonymous) and ip. A page holds up to 500 events. See the API reference for the full shape.

Which vulnerable versions are pulled

The pull census counts the successful downloads in this log per package version and consumer, together with the CI cache hits that are counted there instead of logged, and joins them to the advisories your package policy uses. It answers “which vulnerable versions were pulled in the last 30 days, and by whom” without paging through the raw events, and run_id answers “which versions did this build pull”.

Forwarding it to your SIEM

Access events can be delivered to a SIEM endpoint in the same signed envelope as audit events. The action is registry.access.<action> (for example registry.access.download), and hash_chain is null because access events are not part of the audit hash chain. Delivery is off by default, because download traffic is far larger than audit traffic. Turn it on per endpoint with include_access_log:

curl -sS -X PATCH -H "Authorization: Bearer $FFP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"include_access_log": true}' \
  https://frem.sh/_app/api/v1/orgs/acme/siem/endpoints/$ENDPOINT_ID

An endpoint’s action prefixes apply to access events too. For example, registry.access.upload forwards only uploads. The CI traffic that is not stored as events (above) is not delivered either.

In the data export

A data export contains access-log.ndjson with every access event fremforge still holds for the organisation, one JSON object per line in the same shape the API returns, and metadata/pulled-versions.ndjson with the pull census, where CI cache hits are counted. Both files are covered by the export’s signed manifest.

How long it is kept

Access events are kept for your organisation’s access_log evidence retention: 30 to 730 days. Unset, it follows the audit log retention (90, 180, 365 or 730 days, set at Authentication policy → Audit log retention; default 90). Older events are deleted once a day. While a legal hold is in place, nothing is deleted.

Who can see the addresses

The access log contains personal data: your users’ logins and IP addresses. The API, the SIEM delivery and the export show both as recorded, because this is your organisation’s own record. fremforge staff tooling sees both only as keyed pseudonyms. Log lines the platform writes for its own operations carry neither.

Limits

  • Git clone and fetch, and reads through the REST API (/api/v1), are not registry requests and are not in this log yet.
  • Deleting a package version through the REST API (DELETE /api/v1/packages/...) or the web UI is not recorded here. The deletes a registry client makes under /api/packages are recorded.
  • A request the platform refused before the registry answered, such as an upload rejected by the malware scanner, has no authenticated actor and shows as anonymous.
  • Delivery from the registry to the log is batched every 2 seconds or every 500 events. If the platform is restarted mid-batch, the events of the last few seconds can be lost. Deliberate drops are logged and alarmed on our side.