Scanners

Note

These APIs are subject to change at any time and are for internal use only.

Post - Push results

This endpoint allows a scanner to push results for an existing version.

Note

Requires JWT authentication using the service account credentials associated with the scanner webhook.

POST /api/v5/scanner/results/
Request JSON Object:

  • version_id (integer) – The primary key of the add-on version.

  • results (object) – The scanner results.

Status Codes:

  • 201 Created – Result created successfully.

  • 400 Bad Request – Invalid payload.

  • 403 Forbidden – Authentication failed or the authenticated user is not the service account of an active webhook with a push event.

  • 409 Conflict – One or more of the matched rules have already been pushed for this version.

Patch - Update results

This endpoint allows to update scanner results.

Note

Requires JWT authentication using the service account credentials associated with the scanner webhook.

PATCH /api/v5/scanner/results/(int: pk)/
Query Parameters:

  • id (string) – The scanner result ID.

Request JSON Object:

  • results (object) – The scanner results.

Status Codes:

Query rules

These endpoints allow authorized users to create and run ScannerQueryRule objects and to read their matches.

Note

Requires JWT authentication. The authenticated user must belong to a group with the Admin:ScannersQueryView permission for read operations, and Admin:ScannersQueryEdit for create, update, delete, run and abort operations.

A rule can only be edited while it is in the new state; once it has been scheduled or run its definition is frozen and a new rule should be created to iterate on it. name and scanner are also frozen after creation and can only be set when the rule is created.

For yara rules the name is inferred from the definition (the rule <name> identifier); any name sent by the client is ignored. For narc rules the name is required.

The scanner field accepts yara or narc. The state field is one of new, running, aborted, completed, aborting or scheduled.

Configuration

Only narc rules have configuration options. configuration is an object whose keys are booleans; unknown keys or non-boolean values are rejected. When omitted at creation, it is populated with the defaults noted below. yara rules must not have any configuration.

  • examine_slug (default false): Run the rule against the add-on slug used for the listing on AMO.

  • examine_listing_names (default true): Run against the add-on name(s) used for the listing on AMO.

  • examine_listing_summaries (default false): Run against the add-on summary/summaries used for the listing on AMO.

  • examine_xpi_names (default true): Run against the add-on name(s) in the XPI.

  • examine_xpi_descriptions (default false): Run against the add-on description(s) in the XPI.

  • examine_authors_names (default true): Run against the name of each author attached to the add-on.

  • examine_normalized_variants (default true): For each string being examined, also examine a normalized variant.

  • examine_homoglyphs_variants (default true): For each string being examined, also examine homoglyph variants.

List / create rules

GET /api/v5/scanner/query-rules/

Return a paginated list of query rules, most recently created first.

Response JSON Object:

  • count (int) – The number of rules.

  • results (array) – The array of rules (see the fields below).

Status Codes:
POST /api/v5/scanner/query-rules/

Create a new query rule. The definition is validated (YARA/NARC compilation and, for YARA, that the rule name matches the name field).

Request JSON Object:

  • name (string) – The exact name of the rule (frozen after creation). Required for narc; ignored and inferred from the definition for yara.

  • scanner (string) – yara or narc (required, frozen after creation).

  • definition (string) – The rule definition (required).

  • pretty_name (string) – Human-readable name (optional).

  • description (string) – Human-readable description (optional).

  • configuration (object) – Scanner-specific configuration (optional, see above).

  • run_on_disabled_addons (boolean) – Run on force-disabled add-ons too (optional).

  • run_on_current_version_only (boolean) – Run on the current listed version only (optional).

  • run_on_specific_channel (string) – Restrict to a channel, unlisted or listed (optional).

  • exclude_promoted_addons (boolean) – Exclude promoted add-ons (optional).

Response JSON Object:

  • id (int) – The primary key of the created rule.

  • scanner (string) – The scanner (yara or narc).

  • state (string) – The rule state (new for a freshly created rule).

  • completion_rate (string) – Progress string while running, otherwise null.

  • results_count (int) – Number of matches recorded so far.

Status Codes:

Retrieve / update / delete a rule

GET /api/v5/scanner/query-rules/(int: pk)/

Return a single query rule. Poll this endpoint to track a run via the state, completion_rate and completed fields.

Status Codes:
PATCH /api/v5/scanner/query-rules/(int: pk)/

Update a query rule. Only allowed while the rule is in the New state. Accepts the same writable fields as the create endpoint.

Status Codes:
DELETE /api/v5/scanner/query-rules/(int: pk)/

Delete a query rule and its results.

Status Codes:

Run / abort a rule

POST /api/v5/scanner/query-rules/(int: pk)/run/

Schedule the rule to run. The rule transitions to the Scheduled state and a background task is enqueued.

Response JSON Object:

  • state (string) – The updated state (scheduled).

Status Codes:
POST /api/v5/scanner/query-rules/(int: pk)/abort/

Abort a scheduled or running rule. The rule transitions to the Aborting state.

Status Codes:

Rule results

GET /api/v5/scanner/query-rules/(int: query_rule_pk)/results/

Return a paginated list of the matches for a rule. Only the definition-safe match information is exposed (the files and metadata that hit), not the raw scanner output.

The list can be filtered and ordered with the query parameters below. Invalid filter values return a 400.

Query Parameters:

  • was_blocked (boolean) – Only results whose version was blocked.

  • was_promoted (boolean) – Only results whose add-on was promoted.

  • was_signed (boolean) – Only results whose file is signed.

  • addon_disabled_by_user (boolean) – Only results whose add-on listing is invisible (true) or visible (false).

  • channel (string) – Version channel, unlisted or listed.

  • addon_status (string) – Add-on status (e.g. public, disabled).

  • file_status (string) – File status (e.g. public, disabled).

  • sort (string) – Ordering field. One of id, addon_adu (add-on average daily users) or version_created. Prefix with - for descending order (e.g. -addon_adu). Defaults to -id.

Response JSON Object:

  • count (int) – The number of results.

  • results (array) – The array of results.

  • results[].id (int) – The result id.

  • results[].was_blocked (boolean) – Whether the version was blocked.

  • results[].was_promoted (boolean) – Whether the add-on was promoted.

  • results[].version (object) – Minimal version representation (may be null).

  • results[].version.id (int) – The version id.

  • results[].version.version (string) – The version number.

  • results[].version.channel (string) – The version channel (listed or unlisted).

  • results[].version.created (string) – When the version was created.

  • results[].version.addon (object) – The add-on (id, guid, average_daily_users).

  • results[].matches (object) – The matched files and metadata, keyed by rule name.

  • results[].created (string) – When the result was recorded.

Status Codes: