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
| Field | Meaning |
|---|---|
occurred_at | When fremforge answered the request (UTC). |
origin | Which component saw the request: registry for the package registry. The dependency proxy writes proxy. |
surface | api (/api/packages/…), oci (/v2/…, the container registry) or web (a file downloaded from the web UI). |
org, package.type, package.name, package.version, package.file | What was asked for. |
repo | For a request made with a Forgejo Actions job token: the job’s repository, <owner>/<repo>. Empty otherwise. |
actions | For 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.digest | sha256:<hex> of the file or manifest that was served or stored, when the registry named it. |
action | download, metadata, upload, delete or other. |
actor | Who 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_ip | The 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_agent | The client’s User-Agent, cut at 256 characters. |
http.method, http.status, http.bytes | The 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_reason | allowed; 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_IDAn 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/packagesare 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.