The audit log

searchcode enterprise writes a separate audit stream: who signed in and who was refused, who searched, read or asked about what, which agent did it on whose behalf, and every change an administrator made. It is yours, not ours — it goes where you point it, in a format your SIEM can tail, and it is never sent to us.

This page is the reference a compliance team or a SIEM engineer needs: what is recorded, the shape of a record, where records go, how long they are kept, and what the stream deliberately does not do.

What you can rely on

• It is always on. There is no licence check, no enabled flag and no output setting that discards records. A licence that lapses does not stop the stream. That is a security property rather than a pricing one: if a lapse could silently stop recording denials, every claim that denials are recorded would depend on the licence.
• Denials are recorded as well as grants. outcome: denied is the half most audit implementations leave out and the half a reviewer asks about first.
• It is a contract. Records carry a version. Changes are additive only: a field or an action may be added; none is renamed or removed. A rule you write against today's stream keeps working.
• It never blocks a request, and it never loses a record silently. See When records are dropped.
• If it cannot be opened, the instance does not start. An instance serving while recording nothing is worse than one that refuses to start, because nothing about it would be visible from outside.

Where records go

audit:
  output: file            # stdout | stderr | file | syslog
  retentionDays: 400      # 0 keeps everything
  logSearchQueries: true
  syslogAddress: ""       # only with output: syslog

On stdout, audit records and application log lines share one stream. Every audit record carries version and action, and no application log line carries either, so a forwarder separates them on those fields. If you would rather not separate them at all, use file.

A remote syslog address opens an outbound connection. It is one of the three things that can make this process connect anywhere, all of which you configure; see trust.

The audit block takes effect at start. Changing it needs a restart, because the sink is opened once, before anything that produces records.

At start the instance logs where the stream is going (audit stream configured, code e5b93f74), with the output, the directory, the retention, whether query text is recorded, and the schema version. That line answers "where do our access denials go" without anybody reading the configuration.

Retention

audit.retentionDays defaults to 400: a thirteen-month audit cycle plus a month. 0 keeps everything forever.

Retention applies to output: file. It runs once at start and then every twelve hours, and it is the only thing that ever deletes an audit record. It deletes whole day files: a record lives until its entire UTC day has aged out, so the effective window is up to a day longer than configured. Erring long is the right direction for an audit trail.

With stdout, stderr or syslog, records leave the process as they are written, and retention is whatever your log pipeline keeps.

The shape of a record

One JSON object per line:

{
  "version": 1,
  "ts": "2026-10-15T03:12:44.318Z",
  "id": "evt_8f3a21c49d07b2e6a15c",
  "action": "search.performed",
  "uniqueCode": "a1b2c3d4",
  "trace_id": "4bf92f3577b34da6",
  "actor": {
    "id": "a.person@example.com",
    "type": "agent",
    "name": "a.person",
    "email": "a.person@example.com",
    "groups": ["engineering"],
    "key_id": "k_7d2e",
    "client": "Claude Code — laptop",
    "source": "apikey"
  },
  "target": {"type": "repository", "id": "example__billing-service"},
  "outcome": "allowed",
  "metadata": {"query": "retry backoff", "results": 12, "surface": "mcp"}
}

The values above are illustrative; which fields are present depends on the action.

Outcomes

A rule that only knows the first five still reads every record correctly: the last two were added later and moved records out of not_found and error, so what remains under those words is still true.

Three identifiers

action, uniqueCode and trace_id answer three different questions, and none of them substitutes for another.

• action is what semantically happened. There are a few dozen, they are documented below, and they are the contract with your compliance team. Write rules against these.
• uniqueCode is which line of the product said it. The same action can be written from several places — auth.proxy_rejected comes from five, because an untrusted peer, a wrong shared secret and a duplicated identity header need different answers — and the code tells them apart. It is the contract with support. See log codes.
• trace_id is which request. Every response carries it in an X-Request-Id header, and every application log line written while serving that request carries it too. That is the join: the audit record says what happened and to whom; the log lines for the same trace_id say everything else.

A caller may supply its own X-Request-Id (8 to 32 lowercase hex characters), or a W3C traceparent, whose trace id is adopted, so an instance behind an instrumented proxy correlates with it. Anything else is discarded and a fresh identifier is made.

No error response carries a unique code. Distinct codes for "no such user" and "wrong password" would tell an attacker which one it was. The response carries X-Request-Id; you have the logs, and the logs carry the code.

What is recorded

Every action the product can write is in this list. It is closed: a new action is added here before anything writes it.

Signing in — auth.*

Questions about the policy — authz.*

Reading code — search.*, repo.*, file.*, estate.*

The reads are separate actions on purpose. "Who pulled the estate's risk ranking" and "who listed this repository" are different questions, and one action covering both would make each unanswerable.

Agents — mcp.*, apikey.*, credential.*, oauth.*

Accounts — user.*

The estate — repo.*, connection.*

Operating the instance — config.*, admin.*, license.*, audit.*

Should a record ever arrive under a name that is not in this list, it is written anyway, counted as unknown_actions on /api/v1/status, and logged. A record under an undocumented name can be recovered; a dropped one cannot.

Search query text

audit.logSearchQueries defaults to true. Set it to false and the query text is removed from every record before it is written — the query, query_text and terms metadata keys — whichever surface produced it. Everything else stays, including the result count, so usage reporting keeps working.

This is enforced in one place, inside the audit stream itself, so a surface added later cannot leak query text by forgetting. Recording what developers search for is regulated in some jurisdictions, and this is the setting to show a works council.

When records are dropped

Writing a record never makes a request wait. Records go onto a bounded queue of 4,096 with one writer behind it, so a wedged syslog daemon or a slow disk cannot become a slow search.

If the queue fills, the record is dropped, and the drop is never silent:

• It is counted, and the count is on /api/v1/status under audit.dropped, beside emitted, written and write_errors. The admin page shows the same block.
• The first drop is logged at once (code 6f2b81da), and a sustained overflow is re-reported periodically rather than once per record.
• At shutdown, a run that dropped anything logs that the audit log has a gap (code c9f5a2e4).

An audit log with a recorded gap is a compliance event you can see and explain. One with an unrecorded gap is not. Alert on audit.dropped being above zero.

Who read the audit log?

The stream cannot tell you, and that is by design. Records are written to a file or a stream you own so that getting them out needs no API call: reading them is cat, tail or a forwarder, and the instance is not part of that. There is nothing for it to observe.

If "who read the audit log" has to be answerable, answer it where the read happens: auditd or a file-access policy on dataDir/audit/, the volume's mount policy, or your SIEM's own access log once records are forwarded.

The list carries a reserved audit.exported action for the day an export path exists. No release writes it, and its description says so, because a rule for "the audit log was exported" that never fires could otherwise be read as "nobody has read it".

Feeding a SIEM

The file output is built to be tailed. Fluent Bit, Vector, the Splunk universal forwarder and the Elastic agent all read JSON lines directly. A Fluent Bit input for an instance with dataDir: /var/lib/searchcode:

[INPUT]
    Name    tail
    Path    /var/lib/searchcode/audit/audit-*.jsonl
    Parser  json
    Tag     searchcode.audit

Rules worth writing on day one:

Group, filter and alert on action and outcome, never on wording, and join to the application log on trace_id when you need the detail.

Application logs are a different stream

Application logs are ours, for running the product: JSON on stdout with ts, level, msg, component and uniqueCode, with their own retention and no stability promise beyond the codes. The audit stream is yours, with a schema version and an additive-only promise. They are never mixed in meaning, even when output: stdout puts them on the same pipe. See log codes for the application log, and who sees what for the policy the authz.* records are about.