> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/artifact-registry/3.0/concepts/security-scanning.md).

# Security scanning

Understand how Harness Artifacts scans container images for vulnerabilities and quarantines artifacts that violate your security policies.

Security scanning automatically evaluates every container image for known vulnerabilities at the moment it is pushed to a Docker or Helm OCI registry with scanning enabled.

Security scanning in Harness Artifacts makes vulnerability detection a built-in part of the artifact lifecycle, so a new CVE published against a library inside an already-pushed image is still caught without anyone running a separate step.

## What does security scanning do?

When you configure security scanning on a Docker or Helm registry, Harness automatically creates a pipeline called **HARNESS ARTIFACT SCAN PIPELINE**. This pipeline runs every time a new image is pushed to that registry, including when a new tag is pushed for a digest that was scanned before.

The scan pipeline uses **Aqua Trivy** or **Grype**, selected when you configure scanning on the registry, to inspect the image's file system, operating system packages, and application dependencies for known vulnerabilities.

Results appear on the **Vulnerabilities** tab of the artifact detail page, categorized by severity:

* Critical
* High
* Medium
* Low

Each finding includes the CVE ID, the affected package and version, and whether a fix is available.

No separate pipeline configuration is required. Harness creates and manages the scan pipeline when you enable scanning on the registry.

## How does enforcement work?

Scanning alone surfaces findings; it does not act on them automatically unless you add a policy set.

You can attach a **Security Tests policy set** to a registry. The policy set defines the conditions under which an artifact should be blocked. For example: quarantine any image with at least one Critical CVE. When the scan pipeline runs and finds a result that violates the policy, the image is automatically **quarantined**.

A quarantined artifact:

* Cannot be pulled by users or pipelines.
* Remains visible and auditable in the registry; it is not deleted.
* Can be released from quarantine manually after review, or deleted if appropriate.

Quarantine is not a permanent verdict. It is a hold that gives a security engineer or platform team time to review findings and decide whether the image is acceptable for use.

## The async scanning window

Scanning runs after a push completes. There is a brief window between the moment a push succeeds and the moment the scan result is applied. During that window, the image is technically available. If the scan finds a violation, the image is quarantined after that first window closes. Subsequent pulls are blocked, but the very first pull could succeed before quarantine is applied.

For registries where this window is unacceptable, the recommended approach is a staging-and-promotion pattern: push to a staging registry, wait for scan results, then promote clean images to a production registry. Go to [Configure security scanning](https://developer.harness.io/artifact-registry/3.0/registries/configure-security-scanning.md) for setup details.

For **inbound packages** (dependencies fetched from public upstream sources), Dependency Firewall provides synchronous blocking before the artifact is ever cached. Go to [Dependency Firewall](https://developer.harness.io/artifact-registry/3.0/concepts/dependency-firewall.md) for that use case.

## Aqua Trivy and Grype

Both scanners inspect OS packages and application dependencies in a Docker or Helm image, but they differ in scope and detection behavior:

| Property                        | Aqua Trivy                                                                                      | Grype                                                                                             |
| ------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| OS package coverage             | Alpine, Debian, Ubuntu, Red Hat Enterprise Linux (RHEL), CentOS, and others                     | Broad ecosystem support, container-image focused                                                  |
| Application dependency coverage | npm, pip, Cargo, Maven, Go modules, NuGet, and others                                           | Wide ecosystem support, fewer false positives on application-layer packages                       |
| Vulnerability sources           | National Vulnerability Database (NVD), GitHub Advisory Database, OS-specific advisory databases | Grype vulnerability database, aggregating NVD, GitHub Security Advisories, and additional sources |
| Configuration file scanning     | Yes                                                                                             | No                                                                                                |
| Selection                       | Chosen per registry in the **Security** section of the **Configuration** tab                    | Chosen per registry in the **Security** section of the **Configuration** tab                      |

Go to [Configure security scanning](https://developer.harness.io/artifact-registry/3.0/registries/configure-security-scanning.md) to select a scanner for a registry.

## Integration with STO and SCS

The scan pipeline is built on two Harness modules:

* **Harness Supply Chain Security (SCS)**: Generates an SBOM alongside the vulnerability scan. Go to [SBOM and supply chain](https://developer.harness.io/artifact-registry/3.0/concepts/sbom-and-supply-chain.md) to understand what SBOMs enable.
* **Harness Security Testing Orchestration (STO)**: Orchestrates the scanner execution. With a full STO license, you can add additional scanners beyond Aqua Trivy, configure scan thresholds, and integrate scan results into your pipeline gates.

Both modules are accessible directly from the artifact detail page. You can reference an artifact stored in Harness Artifacts from an SCS or STO pipeline step without configuring an external connector.

## Use cases

**Block images with critical vulnerabilities before deployment**

A platform team attaches a Security Tests policy set to their production Docker registry with the rule: quarantine any image with a Critical severity CVE. A developer pushes a new build that includes a vulnerable version of OpenSSL. The scan pipeline detects the finding, and Harness quarantines the image automatically. The developer receives the finding in the Vulnerabilities tab and updates the base image.

**Ongoing scanning for a production registry**

A security team configures scanning on a registry that holds production-grade base images. Any newly discovered CVE in a previously clean image surfaces in the Vulnerabilities tab without requiring anyone to re-push the image. The team reviews findings weekly and decides whether quarantine or remediation is warranted.

**SBOM generation at push time for compliance**

A team delivering software to a US federal agency must provide SBOMs that meet NTIA minimum element requirements. Every image pushed to their registry generates an SBOM automatically through the scan pipeline. The SBOM is accessible on the artifact detail page and downloadable for submission to the customer.

## Next steps

* To enable scanning on a registry, go to [Configure security scanning](https://developer.harness.io/artifact-registry/3.0/registries/configure-security-scanning.md).
* To manage quarantined artifacts, go to [Quarantine](https://developer.harness.io/artifact-registry/3.0/security-and-compliance/quarantine.md).
* To view scan results and CVE details, go to [Vulnerability scanning](https://developer.harness.io/artifact-registry/3.0/security-and-compliance/vulnerability-scanning.md).

{% @harness-feedback/feedback %}
