Artifactory Sensor User Guide

The Artifactory Sensor User Guide provides instructions for deploying and operating the Artifactory Sensor within the Keyfactor AgileSec Platform. It covers supported authentication methods, scan workflows, configuration options, and how cryptographic findings are collected, processed, and reported.

Overview

Purpose

The Artifactory sensor integrates JFrog Artifactory with Keyfactor's AgileSec Platform to discover, inventory, and analyze cryptographic assets across your artifact repositories.

Key Features

• Multiple Deployment Options: Run via web UI, API, or CLI in your own environment

• Comprehensive Cryptographic Discovery: Automatically identify certificates, private keys, keystores, and cryptographic libraries embedded in artifacts

• Incremental Scanning: Efficiently scans only new or modified files in subsequent runs.

• Flexible Pattern Matching: Use glob patterns to specify which repositories to scan

• Advanced Filtering: Leverage Artifactory Query Language for fine-grained artifact filtering

• Intelligent Batching: Handles repositories exceeding available disk space through configurable batch processing

• Broad Support: Scan local, remote, virtual, or federated repositories

Architecture and Data Flow

High-Level Architecture

The Artifactory sensor operates as a unified sensor plugin. It uses JFrog's Artifactory client to enumerate repositories and download the content to scan. It then passes these download batches to the unified sensor for scanning and then securely transmits the findings to the Keyfactor AgileSec Platform.

Scan Flow

Scan Flow Description

• Authentication: Sensor authenticates to Artifactory REST API via access token. Connectivity is validated with /api/system/ping.

• Enumeration: Queries available repositories

  • Applies include/exclude pattern filters

  • Filters by repository type (LOCAL, VIRTUAL)

  • Filters by package type (YUM, OCI, maven, npm, etc.)

• Download: Retrieves batches to scan

  • Uses AQL to query artifacts matching advanced filters

  • Retrieves artifact metadata (size, checksum, modification date)

  • Specialized for large workloads - downloads and scans configurable batches

  • Parallel downloads using configurable threads (default: 5)

  • Skips unchanged artifacts if incremental scanning is enabled

• Binary Scan: Analyzes binary files to discover cryptographic objects.

  • X.509 Certificates: SSL/TLS certificates, code signing certificates, client authentication certificates

  • Keys: RSA, DSA, EC private keys in PEM, DER, and PKCS8 formats

  • Java Keystores: JKS, JCEKS, PKCS12 keystores

  • Tokens: JWT and JWE tokens

  • Container Images: Certificates and keys embedded in Docker/OCI images

  • Code Artifacts: Embedded certificates in compiled code (JAR, WAR, EAR files)

• Enrich: Performs the following: 

  • Transformation: Normalizes and standardizes scan results into a consistent format for processing. 

  • Enrichment: Enhances scan result with additional metadata like labels.

• Transmit: Sends the enriched scan results to Ingestion Service on Keyfactor AgileSec Platform for inventory and policy-based analysis.

  • Executive dashboards

  • Inventory reports

  • Remediation recommendations

  • Trend analysis over time

Post-Scan Flow

Post-Scan Flow Description

• Scan: The Unified Sensor performs scan the as described in previous sections.

• Send Findings: Upon scan completion, the sensor transmits all discovered cryptographic findings to the AgileSec Platform, where they are stored in OpenSearch. All new findings are initially marked with a "pending" status.

• Execute Policies: The platform executes configured policies on the data stored in OpenSearch. Policies calculate a risk score for each finding and save it alongside the finding data. At this point, findings are no longer considered pending, and each is assigned a score classification displayed as: compliant, high risk, medium risk, or low risk.

• Execute Processes: After policy execution completes, backend processes run to read data from OpenSearch and perform operations such as de-duplication and auto-resolution on the findings.

Supported Authentication Methods

The Artifactory sensor supports API token authentication.

In the Artifactory UI, click on your profile in the top right corner of the screen and select "Set Me Up". Select the "Generic" client and generate an access token for any repo.

Running the Sensor

The sensor can be executed through the platform user interface, via the Scan API, or remotely using the Unified Sensor CLI.

To start, first navigate to the AgileSec Platform UI and click on "Sensors".

Platform Scan Execution

Running the sensor through the user interface is the simplest and fastest way of getting started. It runs the scan in a dedicated environment.

In the sensors UI, click on: "Choose a Sensor" then the Artifactory sensor.

Platform Configuration

Fill in the information shown in the UI:

Scan Execution Using API

Programmatically trigger scans through REST API calls, enabling seamless integration with CI/CD pipelines, automation workflows, and custom applications. API execution provides flexibility for developers to incorporate cryptographic scanning into their existing development and deployment processes.

• Ideal for automated workflows and CI/CD integration

• Supports asynchronous scan execution

• Enables batch scanning of multiple repositories

• Provides programmatic access to scan status using callback.

Note: For complete API reference see the API document.

API Access Token

1. Open your browser and navigate to AgileSec Platform UI

2. Log in with your Keyfactor credentials

3. Click "Access Tokens" in the main navigation menu

4. Click "Generate Token" button

5. Set Token Type to API Token and provide the required details

6. Click "Generate" and copy the generated token

API Endpoint

POST https://<platform-url>/v3/scan/create

Request Format

Headers

Content-Type: application/json

isg-api-token: <your-api-token>

Request Body

The complete request body contains sensor configuration in the sensorConfig field, i.e:

{
"sensorName": "<sensor name>",
  "sensorType": "Artifactory Sensor",
  "sensorConfig": {
      "artifactory_url": "",
      "artifactory_token": "",
      "include_repos": [],
      "exclude_repos": [],
      "aql_extra_parameters": ""
  },
  "callbackId": "<callback id>",
  "labels": [
      {
          "<label name>": "<label value>"
      }
  ],
  "priority": "<priority>",
  "incrementalScan": true,
  "autoResolutionInterval": 5
}

API Field Descriptions

See the Remote Sensor Configuration section for details.

Remote Scan Execution

In the sensors UI, click on "Remote Scan".

Download the sensor for your OS and generate a token.

Remote Sensor Configuration

The remote sensor contains an example configuration file in the directory config/sample-configs/artifactory.yml.

It contains the follow fields:

Populate a configuration file and run the sensor as shown:

./unified_sensor_linux -c ./my_config.yml

Incremental Scanning

Incremental scanning enables the sensor to efficiently scan only changes since the last scan, significantly reducing scan time and resource usage for repositories that are scanned regularly.

How Incremental Scan Works

When incrementalScan is enabled with an autoResolutionInterval (e.g., 5), the scanning follows a cyclical pattern:

Scan Cycle:

1. Full Scan (count = 0): The first scan is always a full scan resulting in a scan of all files. No auto-resolution runs on the first full scan.

2. Incremental Scans (count = 1 to N): The next N scans (where N = autoResolutionInterval - 1) are incremental. Each incremental scan:

   • Compares the current context with the stored context

   • If unchanged, exits early (no new files)

   • If changed, fetches only new or modified files since the last scan

   • Scan count increments with each scan

3. Full Scan + Auto-Resolution (count wraps to 0): After N incremental scans, the count resets to 0 and triggers a full scan. After this full scan, the backend process also triggers Auto-Resolution.

4. Cycle Repeats: This flow continues for subsequent scans.

How Auto-Resolution Works

Auto-resolution runs only at the end of a full scan (when the scan count wraps back to 0). It automatically marks findings as "resolved" when they were detected in previous scans but are no longer present in the latest full scan. For example:

After the auto-resolution process completes, open the findings tab of the original scan history in which the findings were first discovered. You will see that the findings have been marked as "Resolved".

Important Notes:

• Auto-resolution does not run for incremental scans, only subsequent full scans

• Findings removed during incremental scans will be auto-resolved at next full scan

Troubleshooting

Remote Repositories

Downloading from REMOTE repo (cache) is not supported by Artifactory. Instead, scan a virtual repo which contains that desired remote repo.

Forbidden Error (403)

1. Verify Read permissions on target repositories

2. Check permission target configuration

3. List accessible repos:

4. curl -H "Authorization: Bearer ${ARTIFACTORY_TOKEN}" \

5. https://company.jfrog.io/artifactory/api/repositories\

6. | jq '.[].key'

Empty Scan Target

Make sure to specify an include_pattern which matches one of the repositories in the Artifactory instance.

Large Files

This sensor is specialized for very large workloads, where the total size of the repo exceeds the total disk space on the runner. It handles this by batching the content into smaller chunks which are scanned individually.

For details on the size of the batches and how compressed files are handled, see the remote configuration.

Getting Support

Collect diagnostic information:

• Sensor version

• Configuration file (redact tokens)

• Log output

• Artifactory version

Contact Support:

• Email: support@keyfactor.com

• Portal: https://support.keyfactor.com