Scan Report (V3) - HiddenLayer Docs

Scan results use the v3 report schema. The sections below describe the fields you typically use when reading CLI or API output. For the full schema, see the Get scan results API in the HiddenLayer Developer Portal (Console login required). For a response without file-level results, see Get scan result summary.

Report structure

Section	Description
`scan_id`, `status`, `start_time`, `end_time`, `version`, `$schema_version`	Scan identity, lifecycle status (`pending`, `running`, `done`, `failed`, `canceled`), timing, and schema/scanner versions.
`inventory`	Model identity and scan request context (name, version, source, requested location, origin, provider details when available).
`intelligence`	Optional model intelligence such as country of origin, licenses, and usage policies.
`summary`	Aggregate finding counts, threat classifications when available, threat level, and scan coverage. Prefer these fields over deprecated top-level duplicates such as `detection_count` or `severity`.
`compliance`	Optional compliance evaluation status (`COMPLIANT` / `NONCOMPLIANT`) and related rule set metadata.
`file_results`	Per-file scan details, hashes, file type metadata, detections, advisories, and scan errors.

Product documentation uses threat level for the rating exposed by API fields such as severity and highest_severity. These field names remain unchanged.

Understanding scan results

Use the scan’s summary to understand its findings, threat classifications, and coverage. The newer threat-summary fields described below are available in supported API responses; CLI field availability depends on the scanner version. See CLI and API availability. Scan status and policy compliance describe separate outcomes: whether scanning finished and whether the result satisfies the configured policy.

Findings

A finding appears in a file’s detections or advisories collection. The scanner determines which collection contains the finding; threat_type does not determine its placement. Findings with threat_type: "vulnerable" can appear in either collection, so check both when looking for vulnerabilities. For the meaning of category, threat type, and threat level, see Finding Classification. This page explains how those values are represented and summarized in a report.

Field	Meaning
`summary.findings_count`	Total findings: detections plus advisories.
`summary.detection_count`	Number of detections, excluding advisories.
`summary.advisory_count`	Number of advisories, excluding detections. This field can be omitted when the count is zero.

Counts represent findings, not distinct files. A scan can have zero detections and still have advisories, including vulnerabilities.

Threat classification

summary.top_threat_type selects the highest-priority classification present in the scan. Its priority order is independent of threat level: malicious → suspicious → unclassified → vulnerable → advisory → none See Threat types for the four finding classifications. Two additional values describe report state:

unclassified: a detection has a missing or unrecognized threat type, such as one produced before threat classification was available.
none: the scan completed without findings. This does not establish that every file was successfully analyzed. It is not a group in summary.threat_types.

Advisories with missing or unrecognized threat types are grouped as advisory. summary.threat_types provides a breakdown keyed by classification. Only groups containing findings are included; none is not a breakdown group. Each group contains:

count: number of findings in the group.
highest_severity: highest threat level within the group (critical, high, medium, or low), omitted if no finding has a ranked threat level.
categories: unique, nonempty finding categories, when available.
mitre_atlas: unique MITRE ATLAS tactic/technique pairs, when available.

For example, a scan can have a malicious detection with a Low threat level and a vulnerability advisory with a High threat level. Its top threat type is still malicious, while the vulnerability group’s highest threat level is high:

{
  "summary": {
    "detection_count": 1,
    "advisory_count": 1,
    "findings_count": 2,
    "top_threat_type": "malicious",
    "highest_severity": "low",
    "threat_types": {
      "malicious": { "count": 1, "highest_severity": "low" },
      "vulnerable": { "count": 1, "highest_severity": "high" }
    }
  }
}

This is a summary excerpt, not a complete scan report.

Scan threat level

summary.highest_severity is the legacy, detection-only threat level summary. It excludes advisories, even when an advisory has a threat level. Prefer summary.threat_types for threat level across both detections and advisories. The Console’s threat level badges represent these values:

`summary.highest_severity`	Console	Meaning
`critical`	Critical	At least one detection, the most severe being critical.
`high`	High	At least one detection, the most severe being high.
`medium`	Medium	At least one detection, the most severe being medium.
`low`	Low	At least one detection, the most severe being low.
`none`	None	Known file types were recognized and no detection threat level was found. Advisories can still be present.
`unknown`	Unknown	No detection threat level or known-file baseline was available, for example when only unknown file types were scanned.

The older summary.severity and top-level severity fields are deprecated and use safe in place of none. Neither none nor safe means that there are no advisories or that the scan is policy-compliant.

Scan status and coverage

Field	Meaning
`status`	Scan lifecycle: `pending`, `running`, `done`, `failed`, or `canceled`. Read findings together with this status.
`summary.file_count`	Total file results counted by the scan, including files that may have failed or have unknown types. It is not a count of successfully analyzed files.
`summary.files_with_detections_count`	Number of files containing detections. Files with only advisories do not contribute.
`summary.files_failed_to_scan`	Number of files whose scan failed.
`summary.unknown_files`	Number of files reported with an unknown file type.

A done scan or a zero finding count does not guarantee complete coverage. Check failed and unknown file counts before interpreting the absence of findings.

Policy outcome

compliance.status is COMPLIANT or NONCOMPLIANT, according to the policy evaluation. It is separate from threat type and threat level: findings do not by themselves determine the policy outcome. compliance.evaluated_at records when that evaluation occurred. An absent compliance result does not mean COMPLIANT.

CLI and API availability

CLI output

CLI v3 JSON is generated locally from the scan results. Its summary is computed even when the scan fails, so read counts together with status. The API completion rules below do not apply to locally generated CLI summaries. Scanner versions using the earlier v3 summary format provide detection/advisory counts and highest_severity, but do not emit top_threat_type, findings_count, or threat_types. Do not expect these newer fields solely because the output uses the v3 schema. For these versions, detections plus advisories give the total finding count; an omitted advisory_count represents zero. Platform feature availability does not change an installed CLI’s output format. Policy compliance is a platform evaluation; local CLI output should not be assumed to contain it. After submitting results, retrieve the API report to read any available compliance result.

Enable threat-classification output

For scanner builds that support VRT output, set HL_MODEL_SCANNER_VRT_OUTPUT=true in the scanner process environment. In Docker, add the following option to your existing docker run command before the image name:

-e HL_MODEL_SCANNER_VRT_OUTPUT=true

In builds with the opt-in feature, the default is false. Enabling it includes finding threat types, richer advisory metadata, and the summary’s threat-type breakdown. It also enables threat-type CLI flags. Older builds may not support this setting; setting an environment variable does not upgrade the scanner. This controls output, not rule definitions. It does not change a detection’s threat level or category. Use a scanner build containing the updated rule metadata to obtain current category and threat level values.

API responses

Request include_threat_types=true to include summary.top_threat_type, summary.findings_count, and summary.threat_types when available. The deployment’s threat-classification feature must also be enabled; without the query parameter or feature, these fields are omitted. Older stored reports can lack the findings count and breakdown even after that feature is enabled.

findings_count and threat_types are populated for scans with status: done; they are omitted for other statuses.
top_threat_type can describe findings received before completion. With no findings, it is none only for a completed scan; otherwise it is omitted.
A completed scan with no findings has findings_count: 0 when the newer summary is available. Its empty threat_types breakdown is omitted.
A missing new field means the value is unavailable, not zero or none. Missing optional category, MITRE ATLAS, or threat level fields within a group do not negate that group’s finding count.

Use the summary counts instead of the deprecated top-level detection_count, file_count, and files_with_detections_count fields.

Other summary fields

Field	Description
`summary.detection_categories`	Unique detection categories found in the scan.
`summary.advisory_categories`	Unique advisory categories found in the scan.
`summary.mitre_atlas`	Deduplicated MITRE ATLAS tactic/technique pairs across all detections.
`summary.referenced_models`	Deduplicated list of external artifact URIs (typically `ngc://...?file=...`) parsed from a NIM container’s `model_manifest.yaml`. These URIs are informational; the referenced files are not scanned automatically. Download artifacts with the NGC CLI and scan them separately. See NIM Container Scanning.

File results

Each entry in file_results describes one scanned file.

Field	Description
`file_instance_id`	Unique ID for the file instance in this scan.
`file_location`	Full path or location of the file.
`status`	File scan status: `skipped`, `pending`, `running`, `done`, `failed`, or `canceled`.
`start_time` / `end_time` / `seen`	Timing for when the file scan started, ended, and was observed.
`details.md5` / `details.sha256` / `details.tlsh`	File hashes when available.
`details.file_size` / `details.file_size_bytes`	File size in human-readable form and bytes.
`details.file_type`	Detected file type (for example, `pickle`, `safetensors`, `keras`).
`details.file_type_details`	Format-specific metadata. Contents vary by file type; see Type-specific evidence.
`detections`	Array of detections for this file.
`advisories`	Array of advisories for this file.
`file_error`	Error messages returned by the scanner for this file, if any.

Detections

Present when a file triggers a detection rule.

Field	Description
`detection_id`	Unique identifier for the detection.
`rule_id`	Identifier of the rule that produced the detection (for example, `PICKLE_0055_202408`).
`risk`	Legacy classification (`MALICIOUS` or `SUSPICIOUS`) retained in older reports. Current scanner output omits this field. Use `threat_type` when available.
`threat_type`	Finding classification, when included in the output. See Finding Classification.
`category`	Vulnerability category (for example, Arbitrary Code Execution).
`description`	Why the detection was raised.
`likelihood` / `impact` / `severity`	Likelihood, impact, and threat level (`critical`, `high`, `medium`, `low`) for the finding.
`mitre_atlas`	Related MITRE ATLAS tactics and techniques.
`owasp`	Related OWASP labels.
`cve` / `cwe` / `cwe_href`	Related CVE and CWE identifiers, plus a CWE URL when available.
`technical_blog_href` / `technical_blog_hrefs`	Links to HiddenLayer technical blog posts related to the finding.
`rule_details`	Optional rule lifecycle notes (for example, deprecated or superseded).

Advisories

The advisories collection contains findings emitted as advisories by the scanner. An advisory can carry a threat type and threat level; its collection does not imply threat_type: "advisory". See Finding Classification for their meaning.

Field	Description
`advisory_id`	Unique identifier for the advisory.
`rule_id`	Identifier of the rule that produced the advisory.
`category`	Advisory category (for example, Model Reference).
`description`	Why the advisory was raised.

Type-specific evidence

file_results[].details.file_type_details includes extra fields for some model formats. Use these fields to understand format metadata that often contextualizes detections.

File type	Evidence fields	What they tell you
GGUF	`subtype`	Format subtype metadata for the GGUF file.
Keras	`subtype`, `keras_version`, `pickle_modules`, `keras_class_name`, `keras_date_saved_at`, `keras_module`	Keras version and module/class metadata. `pickle_modules` lists embedded pickle modules that can relate to arbitrary code execution findings.
NumPy	`subtype`, `numpy_arrays`, `numpy_shape`	Number of arrays and their shapes in the NumPy file.
RDS	`subtype`, `rds_encoding`, `rds_min_reader_version`, `rds_version`, `rds_writer_version`	R serialization version and encoding metadata for the RDS file.
Pickle	`subtype`, `pickle_modules`, `pickle_header` (when present)	Libraries/modules referenced by the pickle and header metadata such as pickle version. Useful when reviewing code-execution related detections.

Not every file type populates file_type_details. Empty objects are normal for formats that do not expose additional metadata.

Finding Classification explains categories, threat types, and threat levels.
AI Bill of Materials (AIBOM) describes the model inventory output and its CycloneDX representation.
Remediation Guide provides category-specific response guidance.

​Report structure

​Understanding scan results

​Findings

​Threat classification

​Scan threat level

​Scan status and coverage

​Policy outcome

​CLI and API availability

​CLI output

​Enable threat-classification output

​API responses

​Other summary fields

​File results

​Detections

​Advisories

​Type-specific evidence

​Related guides

Report structure

Understanding scan results

Findings

Threat classification

Scan threat level

Scan status and coverage

Policy outcome

CLI and API availability

CLI output

Enable threat-classification output

API responses

Other summary fields

File results

Detections

Advisories

Type-specific evidence

Related guides