JAVV API¶

This page describes the HTTP API of JAVV. It is for people who write scripts for JAVV or monitor it. The tasks come first. Then the reference tables give each endpoint, error and metric.

The backend also publishes a description of its API, with each parameter and its limits. It is at /docs and /openapi.json on the backend port, 8000. The frontend does not send these two paths to the backend.

To push scan results from your own tools, read Push from your own script. To connect the JAVV scanners, read Connect the scanners.

Sign in from a script¶

A script uses the same address as a browser. The frontend sends /api, /auth and /readyz to the backend.

Prerequisites:

• bash, curl and jq.
• A JAVV username and password.

Steps:

1. Set the address of JAVV:

   JAVV=https://javv.example.com
   

2. Sign in. The command keeps the session cookie in the file jar:

   read -rs -p 'Password: ' pw && echo
   jq -n --arg u admin --arg p "$pw" '{username: $u, password: $p}' \
     | curl -sf -c jar -b jar -H 'Content-Type: application/json' --data @- "$JAVV/auth/login"
   

   The reply shows must_change. If it is true, do step 3. If it is false, go to step 4.
3. Change the password. The new password must have 12 characters or more:

   read -rs -p 'New password: ' new && echo
   jq -n --arg c "$pw" --arg n "$new" '{current_password: $c, new_password: $n}' \
     | curl -sf -c jar -b jar -H 'Content-Type: application/json' --data @- "$JAVV/auth/password"
   unset new
   

   JAVV signs the user out of each session, then writes a new session cookie to jar.
4. Delete the password from the shell:

   unset pw
   

5. Send your requests with the cookie. For example, show your user and permissions:

   curl -sf -b jar "$JAVV/auth/me"
   

6. At the end of the script, sign out. JAVV then ends the session:

   curl -sf -b jar -X POST "$JAVV/auth/logout"
   

Keep the file jar private. Until the session ends, the cookie in it gives access as your user.

Read a list page by page¶

A list endpoint gives one page of rows. List responses shows the three forms of a list. This procedure reads all the findings of one cluster with the cursor.

Prerequisites:

• A session cookie in the file jar (Sign in from a script).

Steps:

1. Find the id of the cluster:

   curl -sf -b jar "$JAVV/api/v1/clusters" | jq -r '.clusters[] | "\(.cluster_id) \(.cluster_name)"'
   

2. Set the id:

   cluster=<cluster_id>
   

3. Read each page, 500 rows at a time. Send next_cursor back as cursor until it is null:

   cursor=
   while :; do
     page=$(curl -sfG -b jar "$JAVV/api/v1/findings" --data-urlencode "cluster_id=$cluster" \
       --data-urlencode size=500 ${cursor:+--data-urlencode "cursor=$cursor"}) || break
     jq -c '.data[] | {cve_id, scanner, severity, state}' <<<"$page"
     cursor=$(jq -r '.next_cursor // empty' <<<"$page")
     [ -n "$cursor" ] || break
   done > findings.jsonl
   

4. Compare the number of lines in findings.jsonl with total.value of a page. If they are not equal, a page failed. Read the list again.

A cursor stays valid for a short time only. If a page answers 410, start again at step 3.

To stop before the last page, close the cursor. Until then, it keeps one of your open-cursor slots (Exports and reports):

jq -n --arg c "$cursor" '{cursor: $c}' |
  curl -sf -b jar -X POST "$JAVV/api/v1/cursors/close" -H 'Content-Type: application/json' -d @-

Scrape the metrics¶

The backend gives its metrics at /metrics, in the Prometheus format.

• This path needs no sign-in.
• The frontend does not send it to the backend.
• Metrics lists each metric.

Prerequisites:

• A Prometheus that can connect to the backend port, 8000.

Steps:

1. Let your Prometheus connect to the backend port, 8000:
   • with docker compose: publish the port. Use the ports block in comments under backend in compose.yaml (Ports and access).
   • with Helm: use the backend Service. For a release with the name javv, it is javv-backend.
2. Add a scrape of http://<backend>:8000/metrics to your Prometheus.
3. Look at the metrics from a machine that can connect to the port:

   curl -sf http://<backend>:8000/metrics | grep '^# TYPE javv_'
   

JAVV gives no alert rules. Make alerts from the metrics that apply to your setup.

Authentication¶

Each endpoint uses one of four kinds of authentication.

The session cookie has the HttpOnly and SameSite=Lax flags. It also has the Secure flag, unless JAVV_SESSION_COOKIE_SECURE is false (http or https).

• Session time: a session ends JAVV_SESSION_TTL_HOURS after the sign-in (default 24), or at sign-out. The server decides, not the cookie.
• Failed sign-ins: after JAVV_LOGIN_MAX_ATTEMPTS failures (default 5) for one username in JAVV_LOGIN_LOCKOUT_MINUTES (default 15), the sign-in answers 429. All cases of a name are one count: Alice and alice count together. A successful sign-in sets the count to zero.
• One answer for each failure: a wrong username, a wrong password, a disabled user and an expired session all get the same 401. Thus the answer does not show if a username exists.
• The login body: POST /auth/login accepts only Content-Type: application/json. A body that is not JSON gets 422. A different JSON type, for example application/merge-patch+json, gets 415.

A temporary password¶

The first admin, a new user and a user after a password reset have a temporary password. The user must change it (Sign in from a script, step 3). Until then, the session can use only /auth/*: show the user, change the password, and sign out. Each other session endpoint answers a well-formed request with 403 password change required, reads included. A body that is not valid JSON gets 422 first.

Each refusal logs a password change required warning with the username. It also increments javv_auth_failures_total{reason="must_change"}.

A password change¶

POST /auth/password changes the password of the user of the session.

• The new password has 12 to 256 characters. Each character counts as one, also a character outside ASCII.
• 401: the current password is wrong, or the session ended. The two get the same answer.
• 403: an identity provider manages the password of the user.
• 422: the new password has fewer than 12 or more than 256 characters, or the body is not valid.
• The audit row comes first. JAVV writes a pwd_change row to the audit log before it changes the password. If JAVV cannot write the row, the password does not change, and the answer is an error.
• 200 with no cookie: the password changed, but JAVV could not make the new session. Each old session ended, so sign in again with the new password. JAVV logs a password changed, no new session warning and increments javv_auth_failures_total{reason="session_not_minted"}.

Roles and permissions¶

Some endpoints need a permission. The tables in Endpoints name it. A user gets the permissions of its role. The web app uses the capabilities from GET /auth/me to show or hide its controls. The backend checks the permission again on each request.

At its first start, JAVV creates four roles:

The Roles card in the web app shows a name and a short text for each permission. It gets them from GET /api/v1/admin/roles. The backend keeps one list of the permissions, in this order.

can_export controls the export files, not the reads. A user without it can still read each finding through GET /api/v1/findings, 500 rows a page.

Each read and export applies the cluster that the request names. Each user can read each cluster. A cluster_id has 8 to 64 lowercase letters, digits or hyphens, and does not start with a hyphen.

Errors¶

Each answer that is not a success has the same body, with the type application/problem+json:

{"type": "about:blank", "title": "invalid credentials", "status": 401, "detail": null, "request_id": "b169be4a30444fdc"}

• type: about:blank, or one of these. Match on type, not on title: the title can change.
  • store-read-only on a 503 for a write that OpenSearch refused because its disk is full.
  • cluster-delete-unfinished on a 409 for a cluster whose delete did not finish: a bring back (POST /api/v1/clusters/{cluster_id}/unretire) or a new token (POST /api/v1/admin/tokens). Delete the cluster again to finish it.
  • expiry-passed on a 422 for a decision whose expiry is not after today in UTC, or not after now (POST /api/v1/decisions, PATCH /api/v1/decisions/{decision_id}).
• title: a short text that names the error.
• detail: on a 422 from a field check, the list of the fields that are not valid, with the reason for each. It does not hold the value that you sent. Else it is null.
• request_id: the id of the request in the backend log. The X-Request-ID header of the answer also has it, on each answer. To set the id yourself, send X-Request-ID with 1 to 64 letters, digits or hyphens. If you send no id, or an id that is not valid, the backend makes one.

List responses¶

A list has one of three forms. The form comes from how the endpoint pages its rows.

• /findings/groups uses a cursor, but it has no total.
• /notifications puts its rows in items, not in a key with the name of the resource.
• Some answers have more keys next to the list. For example, /images also has inventory.
• In a cursor list, total is an object. In an offset list, total is a number.

Read a key by its name, and check that it exists. In jq, a key that does not exist gives null, and the length of null is 0. That looks the same as an empty list.

Endpoints¶

In the tables, the Access column gives the authentication, or the permission that the endpoint needs:

• none: no authentication.
• token: a scanner token.
• session: any signed-in user.
• a permission name: a signed-in user with that permission (Roles and permissions).

The audit log keeps each sign-in and sign-out, and each change to triage, decisions, settings, the scan scope, users, tokens, saved views, dashboards, clusters, snapshots and jobs. It also keeps each query of the data inspector.

Each signed-in user reads the audit log. Only a user with can_manage_users reads the account events: the rows with entity_type user (sign-ins and sign-outs, password, user and role changes), token (the scanner tokens) and mcp_tool (the tool calls of the MCP tokens). For the other users, the three audit endpoints leave these rows out of the list, the counts and the CSV.

Only a user with can_manage_settings reads the rows with entity_type dashboard. A dashboard row holds the whole dashboard, also a private one, and these users can see each dashboard. For the other users, the three audit endpoints leave these rows out in the same way.

System¶

The backend also writes the release and the mapping version in its bootstrap complete log line.

Scanner endpoints¶

The scanners use these endpoints. Each one applies to the cluster and the scanner of the token, never to values in the body. Push from your own script gives the order of the calls in a scan cycle.

Sign-in and sessions¶

Admin¶

The data inspector¶

POST /api/v1/admin/opensearch/inspect takes {method, path, body} and sends only allowed reads to OpenSearch:

• GET or POST on <index>/_search and <index>/_count
• GET on <index>/_mapping
• GET on _cat/indices, _cat/shards, _cluster/health and _nodes/stats. The _cat reads show only the indices of JAVV.

These requests get 422, with the reason:

• a request on system-users, system-sessions or system-tokens
• a body with script, script_fields, runtime_mappings, pit or scroll
• a size larger than JAVV_INSPECT_MAX_HITS.

An answer larger than JAVV_INSPECT_MAX_RESPONSE_BYTES gets 413. A good answer is {took_ms, bytes, cap_bytes, body}. The audit log keeps each query, with the user, the method and path, and a hash of the query.

The jobs list¶

GET /api/v1/admin/jobs gives {jobs, scheduler}. jobs has one entry for each job kind:

• the last run: status, requested_by, started_at, finished_at, result and error. A job that never ran has status: idle.
• stale: true when a run is running, but it stopped its heartbeat.
• runnable and capability: if you can start the job with POST .../run, and the permission for it. capability is null for a job that you cannot start.
• schedule: the cron expression from JAVV_JOB_<KIND>_CRON, or null.
• next_run_at: the next run, in UTC. It is null when the job or the scheduler is off.
• health, one of these values. The first value that applies is the result:
  1. failed: the last run failed.
  2. off: the job has no schedule, or the scheduler is off.
  3. never_ran: the job has a schedule, but no run.
  4. overdue: two scheduled times passed after the last start.
  5. ok: all other cases.

scheduler is {enabled, timezone}: if this backend runs the schedules, and the time zone of the cron expressions.

Start a background job¶

POST /api/v1/admin/jobs/{kind}/run starts one of three jobs:

• The other five kinds, and a kind that does not exist, get 404.
• If a run of the job is in progress, the request gets 409. The scheduler applies the same rule. Thus one run of a kind at a time occurs.
• ?dry_run=true applies to lifecycle_sweep only. It answers 200 {dry_run, result: {rolled, dropped, errors}} with the counts that a run would give. It changes nothing. On the other kinds, dry_run gets 422.

Findings: read¶

These endpoints need a session only. Each one needs cluster_id, except POST /api/v1/cursors/close.

Filters¶

/findings, /findings/facets, /findings/groups, the findings exports and the saved views take the same filters:

• Each filter except kev, fixable, disagree, present, new_within_days, overdue, unassigned, image_digest and q has an exclude_ form, for example exclude_severity. An exclude_ filter leaves out the rows with that value. A row with no value for the field stays. Thus exclude_assignee=bob keeps the rows with no owner. An exclude_ filter with more than one value leaves out the rows with any of the values.
• package_name is not a facet. fields=package_name gets 422.
• In a saved view (preset) and in a report (params), the filters that take more than one value (namespace, ptype, assignee, image_repo, cve_id, package_name and their exclude_ forms) also take one string. JAVV keeps it as a list with that one value.
• One field takes the filter or its exclude_ form, not both. assignee and unassigned also do not go together. Each of these pairs gets 422, also in a saved view and in a report.

A past time: as_of¶

Each read takes as_of. With no value, now or a time in the future, the read shows the current state. With a time in the past, JAVV builds the state at that time from the history:

• kev, epss, disagree, image_repo, tag and app are not in the history. They are null in the rows.
• The SLA deadline (overdue and due_at) uses the KEV value that each scan recorded, as a read now does. A scan that JAVV received before release 0.9.1 has no KEV value in the history. A finding from such a scan gets the deadline of its severity.
• A filter, sort or group on one of these fields gets 422. image_repo and exclude_image_repo get 422 too.
• A facet on one of these fields gives no values.
• ptype, package_name and the exclude_ filters on recorded fields apply as usual.
• The CSV and VEX exports of findings get 501. A report (POST /api/v1/reports) can use a past as_of_t.
• The audit log and the failed pushes end their window at that time.

Trends¶

• /trends/scans: the committed scans. interval is day (default) or hour. hour is possible only for 31 days or less, else 422. At a past as_of, the intervals are days.
• /trends/findings: the new findings and the resolved findings. resolved counts only the findings that a scan no longer showed (resolved_semantics: "scan_resolved"). A triage to resolved does not count. split is scanner (default) or severity. split=severity gets 422 at a past as_of. scanner (trivy or grype) limits the series to one scanner.
• /trends/ingest-failures: the same days and interval as /trends/scans, so the two series align. It gives {series: {<scanner>: [{date, count}]}, days, interval}. With no refused push, series is {}.

Failed pushes¶

GET /api/v1/scanners/ingest-failures gives {data, total, next_cursor}. Each row has @timestamp, failure_id, scanner, stage, reason, status, error and image_ref. The ingest rejected log line has the same failure_id. The read uses no point in time. Thus a push that fails during your read can show on a later page.

The clusters list¶

GET /api/v1/clusters gives each cluster that has a token, a name or a retirement record. cluster_name is a name to show. JAVV never uses it in a query. Without a name, it is the cluster_id. Each row has:

• retired. A retired cluster is in the list only with ?include_retired=true. A cluster that sent a scan after its retirement is not retired.
• last_scan_at: the newest accepted scan, or null.
• silent_since: the start of the retirement countdown. This is the newest accepted scan, else the first token, or the return from retirement if that is later.
• warns_at and retires_at. null means that the cluster never retires.
• delete_started: true when a delete of the cluster started and did not finish. Delete it again.
• retirement_mode: manual or auto for a retired cluster, else null. A manual retirement revoked the tokens. To bring the cluster back, make a new token.

Findings: triage and decisions¶

The approvals queue¶

GET /api/v1/decisions/approvals takes size and offset, and these filters:

• q: a part of the CVE id.
• status: active, expiring, expired or open-ended. JAVV calculates it from expiry at the time of the request. warn_days (default 7) sets when expiring starts.
• created_by.
• scanner: both, trivy or grype.

status and created_by take several values, for example status=expired&status=expiring, at most 32 for each filter. An acceptance matches when it has one of the values. q and scanner take one value. Each filter except q has an exclude_ form. An exclude_ filter with several values leaves out the acceptances with any of them. The answer also has facets: the counts of status, created_by and scanner with the same filters. The created_by counts leave out the created_by and exclude_created_by filters, so the other approvers keep their counts. A revoked acceptance is never in the queue.

contains is a value search on the created_by values, with 2 to 128 characters. It gives the approvers that contain the text, in any case, from all approvers and not only the 32 with the most acceptances. The counts use the same filters and warn_days as the created_by counts. The answer has only facets.created_by, with at most 32 values, and more. more is true when more approvers contain the text. The answer has no rows and no total.

The CSV export has the same rows. A file larger than JAVV_EXPORT_MAX_ROWS rows gets 413. Two columns are different from the screen:

• JAVV calculates status for each row, with the same rules as the status filter.
• scope_namespaces and scope_images give the full lists. If both are empty, the acceptance applies to the full cluster.

Settings¶

Configuring JAVV gives the defaults and the limits of each runtime setting.

Clusters¶

Delete a cluster¶

DELETE /api/v1/clusters/{cluster_id} deletes all the data of a retired cluster, except its rows in the audit log. Snapshots from before keep the data.

1. It writes a marker for the delete.
2. It deletes the tokens of the cluster. A scanner that still pushes gets 401.
3. It deletes the history indices of the cluster.
4. It deletes the rows of the cluster in findings, javv-scan-watermarks, javv-scan-orders, system-decisions, system-notifications and system-reports.
5. It deletes the settings and the name of the cluster, then its retirement record.

6. It marks the delete as finished.

7. A cluster that is not retired gets 409. A cluster that does not exist gets 404.

8. If an admin brings the cluster back while the delete starts, only one of the two goes ahead. When the delete loses, it gets 409 and deletes nothing. When the bring back loses, it gets 409, and the delete continues.
9. If a step cannot finish, or OpenSearch is not available, the request gets 503. Send the request again. The delete continues from the step that stopped.
10. The answer is {cluster_id, deleted: {<what>: count}}.
11. The marker stays. Each night, the retirement sweep deletes the rows that a push wrote after the delete. Before it deletes them, it writes an audit row with their counts. After a second pass with no rows, or if the cluster comes back, the sweep deletes the marker. A new token for the cluster's ID also deletes the marker: the cluster is back, and JAVV keeps its new data.
12. A second delete of the same ID, after the cluster came back, writes its own marker.

Saved views¶

Dashboards¶

A dashboard is a layout of panels. It holds no data: each panel gets its data with the permissions of the user who opens the dashboard.

Who can see a dashboard:

• sharing: private: the owner only
• sharing: everyone: each user
• sharing: roles: the users with one of the roles in roles
• a user with can_manage_settings: each dashboard

The fields that you set:

Each panel:

The backend refuses with 422:

• a field that is not in these lists, or a panel ID that it does not know
• a height that the panel does not have, or a scanner on a panel with no scanner data
• filters on a panel that does not read findings counts
• scanner or exclude_scanner in filters. The scanner field of the panel does this.
• state or exclude_state in the filters of triage-progress. This panel shows each state.
• audit_filters on a panel other than triage-activity, or entity_type in audit_filters
• a field and its exclude_ form in audit_filters, as the Audit log refuses them
• an action in audit_filters that is not a triage action. The panel counts only the triage rows.
• a panel outside the two columns, or two panels that start on the same cell. A panel holds only the cells of its top row: one cell for a width of 1, and both cells for a width of 2. The height takes no part in this check, because the page makes each panel as tall as its content.
• roles without sharing: roles, or sharing: roles without a role

JAVV writes owner, created_by, created_at, updated_by, updated_at and revision. Each change adds 1 to revision. The audit log has a row for each change (dashboard_create, dashboard_update and dashboard_delete).

Dashboard files¶

A dashboard file is NDJSON: one dashboard on each line, then one summary line. A line has dashboard_id, schema_version, name, description, scanner, panels, sharing and roles. A line has no owner, user names or times. The summary line is {"exported_count": N, "missing_ids": [...]}. A missing ID is an ID that does not exist or a dashboard that you cannot see. The export does not need can_export.

The export sorts the dashboards by name. Without dashboard_id, it gives the first 1,000, and the summary line does not tell if there are more. The IDs are in the URL: each ID adds approximately 45 characters. A URL longer than 16 KB (approximately 350 IDs) gets 431 from the frontend server.

The import reads the file as the body of the request, with Content-Type: application/x-ndjson. A different type gets 415.

• You are the owner of each dashboard that the import makes. The audit log gets a dashboard_create row for each one.
• The import ignores owner, created_by, created_at, updated_by, updated_at and revision in a line. JAVV sets them.
• Each line gets the checks of POST /api/v1/dashboards. A dashboard_id has 32 lower-case hexadecimal characters. A line must be UTF-8. The import ignores a byte order mark at the start of a line. An object in a line has at most 14 fields. A field that is in an object two times counts two times.
• A line can have a role from a different JAVV. If this JAVV has no role with that name, the line gets 422 (unknown_role), and the line does not make a dashboard.
• A line ends at a line feed (\n). The import ignores a \r before it. It skips empty lines and the summary line of an export.
• The result of a line is 201 (made), 409 (the ID exists) or 422 (the line is not valid). A 422 gives the place and the reason of each error, not the value of the file.
• With copy=true, each line gets a new ID, so no line gets 409.
• A file larger than JAVV_DASHBOARD_IMPORT_MAX_BYTES gets 413. A file with more than 1,000 lines that are not empty also gets 413, also when some of those lines are not valid. The summary line of an export is not in this count. After a 413, the import makes no dashboard.
• A line that makes a dashboard is 3 requests to OpenSearch. 100 such lines take approximately 5 seconds.
• If OpenSearch refuses a write, the import stops and the answer is the error (for example 429 or 503), without the results. The lines before that line have their dashboards. To complete an import without copy, send the same file again: the dashboards that exist get 409. To complete an import with copy=true, count the dashboards that the import made: you are the owner, and their created_at is after the start of the import. The import writes the lines in the order of the file. Thus, delete that number of valid lines from the start of the file, and send the other lines with copy=true.

The answer has results and the counts created, conflicts and invalid. Each result has line and status. A 201 or 409 result also has dashboard_id, and a 422 result has errors.

Exports and reports¶

In each CSV file, JAVV puts an apostrophe before a cell that starts with =, +, -, @, a tab or a carriage return. Thus a spreadsheet does not run the cell as a formula.

Each user can have JAVV_MAX_CONCURRENT_PITS_PER_PRINCIPAL (default 10) open cursors and exports at the same time. One more gets 429 with Retry-After. A cursor is open from its first page until its last page, until you close it with POST /api/v1/cursors/close, or until JAVV_SEARCH_PIT_KEEP_ALIVE plus 30 seconds after the last page that you read. JAVV keeps the result of a report in OpenSearch for JAVV_EXPORT_TTL_HOURS (default 24). The report_drain job runs the queue, on JAVV_JOB_REPORT_DRAIN_CRON (default every 5 minutes). A result larger than JAVV_EXPORT_MAX_BYTES makes the job fail. Before a bulk triage job writes, it checks its patch again. A patch that is not valid makes the job fail, and the error of the job names the field, not its value. At the end of a job, a report_ready notification goes to the user.

Notifications¶

The types are report_ready, sla_breach, assignment and cluster_retiring:

• The retirement sweep sends cluster_retiring to each user with can_manage_settings when a cluster starts its warning period. It sends it one time for each silence. ref is the retires_at of the cluster.
• The sweep deletes these notifications when the cluster scans again, or when a return from retirement starts a new silence. A change of the settings keeps them.

Ingest a scan¶

POST /api/v1/ingest/scan accepts the results of one scan: an envelope with schema_version 3 or 4, as JSON. The body can have Content-Encoding: gzip. The findings of a version 3 envelope have ptype: null. Push from your own script gives the schema, the order of the calls and an example.

The backend does these checks in this order:

1. The Authorization header starts with Bearer.
2. The token is not over its rate limit. The limit applies to each token value, before the backend looks for the token.
3. The token exists, is not disabled, and is not expired.
4. The compressed body is not larger than its limit. The backend counts the bytes as they arrive, and does not trust Content-Length.
5. The body after gzip is not larger than its limit.
6. The body is JSON.
7. The envelope is valid. A field that the schema does not have makes it not valid.
8. The cluster_id and scanner of the envelope are the ones of the token.
9. The scan_order is not larger than the largest one that POST /api/v1/scan-runs gave to this cluster and scanner.
10. The last_seen_at is not more than JAVV_INGEST_FUTURE_TOLERANCE_MINUTES ahead of the backend's clock, and not older than the staleness period of the cluster.

Then the backend writes the findings. Each finding has a fixed id. Thus when a scanner sends the same envelope again, JAVV keeps one copy. Two entries of one envelope with the same vuln_id, package_name and package_version are one finding. The backend keeps the values of the last entry, and it counts the finding one time.

Configuring JAVV gives the limits and their defaults.

Logs of a refused push¶

Each refused push increments javv_ingest_rejected_total{reason}. A push that the backend refused after the token check (400, 403, 413, 422 or 503) also writes one ingest rejected warning. The warning has these fields:

• always: reason, status, the cluster_id and scanner of the token, and failure_id
• on a 413: limit_bytes
• on a 422 for an envelope that is not valid: errors, the count of errors
• on a 422 for unallocated_order: scan_order, and max_allocated, the largest order given
• on a 422 for clock_skew: last_seen_at, and freshness_days when the time is too old
• on a 503 because OpenSearch is not reachable: error, the kind of the connection error
• on a 403: payload_cluster_id and payload_scanner.

The backend never logs the token. A 429 writes one warning for each token in each minute, at most. A 401 writes no warning, so that a sender with no token cannot fill the log.

Records of a refused push¶

The backend also keeps each push that it refused after the token check. It writes one document to javv-ingest-failures-<cluster_id>, with the cluster and scanner of the token. The Failed ingests table on the Scanner status page and GET /api/v1/scanners/ingest-failures show these documents. A 401 and a 429 make no record.

The answer to the scanner does not depend on the record. If the backend cannot write the record, it logs ingest failure not recorded with the failure_id. It also increments javv_ingest_failures_unrecorded_total{reason}.

The MCP endpoint¶

An AI agent, for example in Cursor, VS Code or Codex, reads and changes JAVV data through the MCP endpoint at POST /api/v1/mcp. The endpoint exists only when JAVV_MCP_ENABLED is true (MCP endpoint). An admin makes the token in POST /api/v1/admin/mcp-tokens (Admin).

The endpoint takes the MCP protocol versions 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05. A client of an older version starts with initialize. The endpoint keeps no session: it never sends Mcp-Session-Id, and each request carries its token.

Before the MCP server reads a request, the endpoint checks it in this order:

The 401 and the 403 only count in javv_auth_failures_total, with no log line: a sender can repeat them with no limit. A 429 also logs mcp rate limited with the token.

A request that passes the checks is the principal mcp:<name> of the token. The token writes last_used_at at most one time a minute.

The level of the token sets the tools that the token can see and call:

The tool list of a token (tools/list) holds only the tools of its level. A call to another tool is a tool error with 403, and it also writes its audit row. Read tools have the hint readOnlyHint. Write tools have the hint destructiveHint. A client can use this hint to ask the user before a write.

Each tool call writes one audit row after the call, and one mcp tool call log line:

If JAVV cannot write the row, the call is a tool error and the agent gets no data. After a write, the error tells the agent that the tool made the change, so that the agent does not make it again.

The answer of a tool is one text with compact JSON.

• A tool error gives the status and the text of the route. For an argument that is not valid, it gives the name of the argument and the reason. It never holds the value of an argument.
• An answer longer than JAVV_MCP_MAX_ANSWER_CHARS loses rows from the end of its longest top-level list. Its cut field then gives the list, the rows that it kept and the rows that it had.
• A page with a next page (next_cursor) is not cut, because the next page starts after the last row of the full page. If the page is longer than the cap, the call is a tool error that tells the agent to ask for a smaller size.
• An answer with no top-level list that is longer than the cap is a tool error. For example, a trend over many days in trends can be longer than the cap. Then the agent must ask for fewer days. After a write, the error tells the agent that the tool made the change.

The read tools. Each read tool calls the function of one route. It takes the parameters of that route, with the same names, types and limits. It gives the answer that the route gives to an admin, for each level of token. Thus the agent also sees the account rows of the audit log and each dashboard.

A tool with more than one kind takes the parameter kind. A parameter that the kind does not take is an error, and a missing parameter that the kind needs is an error. A missing parameter that the kind does not need takes the default of the route.

These reads have no tool. test_mcp_read_coverage.py fails when a new GET route has no tool and is not in this list, NO_TOOL in backend/src/backend/mcp/read_tools.py.

The write tools. Each write tool calls the function of one route, with the principal mcp:<name> and only the permissions of the token level. Before the call, it runs the permission check of the route. The route then does all its own checks, and it writes its own audit rows with the actor mcp:<name>. For example, a write token cannot set the state risk_accepted. With set_triage and bulk_triage, it cannot change the state of a finding with an accepted risk. But a not_affected decision for a smaller scope has precedence over a risk accept for a larger scope, as on the screens. For example, a not_affected decision for one image has precedence over a risk accept for the cluster.

A write route that is not in this table has no tool. test_mcp_read_coverage.py fails when a write tool uses another route.

Metrics¶

GET /metrics gives these metrics, in the Prometheus format (Scrape the metrics).

The backend also gives the default process and garbage collection metrics of prometheus_client. A scrape does not use OpenSearch. Thus the metrics stay available during an OpenSearch outage. The backend runs one process, and the metrics are for that process.

Client events¶

The body is {events: [{level, event, fields}]}, with 1 to 20 events:

• level is warn or error. Other values get 422.
• event matches ^[a-z0-9][a-z0-9 ._-]{0,63}$.
• fields has at most 25 keys in each object, at most 3 levels, keys of at most 64 characters, values of at most 512 characters, and lists of at most 20 items.

A body that does not agree with these rules gets 422.

The backend writes each event as client.<event>, with client_event=true and the username. Thus an event from a browser cannot look like an event of the backend. The fields of the event stay under one fields key. Thus a browser cannot set the username of the log line. The log redaction also applies inside fields.

Each user can send JAVV_CLIENT_EVENTS_RATE_LIMIT_PER_MINUTE requests in each minute. One more gets 429 with Retry-After. It also increments javv_limit_rejections_total{limit="client_events"} and logs a warning. The backend checks the body before the rate limit. Thus a refused body writes nothing to the log.

A session with a temporary password gets 403. A request with no session gets 401.

Logs¶

The backend writes JSON log lines to its standard output.

• Request id: each line of a request has its request_id. Errors tells how to set it. Each line of a push also has the cluster_id and scanner.
• Unexpected errors: an error with no handler logs one unhandled error line at the error level, with the stack, method, path and request_id. The answer is a 500 with the same request_id.
• Redaction: the backend replaces the value of each key that contains token, secret, password, authorization, pepper, session or cookie. It also replaces each Bearer ... text. No log line has a token.
• OpenSearch bodies: the backend never logs the body of a request to OpenSearch, or of its answer, at any log level.