Artifactory Sensor User Guide

The Artifactory Sensor User Guide provides instructions for deploying and operating the Artifactory Sensor within the Keyfactor AgileSec Platform. This guide covers supported authentication methods, execution methods, configuration options, and troubleshooting.

Refer to Sensors Architecture and Overview for additional details on sensor architecture, including data flows, incremental scanning, and auto-resolution.

Overview

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

Prerequisites

Artifactory Requirements

Requirement	Details
Protocol	HTTPS required for API access.
Access	Network connectivity from the sensor machine to the Artifactory API.
API Access	A valid Artifactory API token.

Remote Execution Requirements

If running the unified sensor remotely using CLI:

Component	Requirement
Operating System	Linux (x86_64, x86_64): Ubuntu 18.04+, RHEL 9+, CentOS 8+, Debian 10+ Windows (x64): Windows Server 2016+, Windows 10+ macOS (Intel, Apple Silicon): macOS 10.15+
RAM	3 GB minimum, 4 GB recommended for large repositories
Disk Space	Minimum 2x Size of your repository.
Permissions	Read/Write access to working directory

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 Artifactory Sensor can be executed using the following methods:

Platform Scan Execution: Configure and execute scans directly though the Keyfactor AgileSec web UI with on-demand or scheduled execution options.
Using API: Programmatically trigger scans through REST API calls, enabling integration with CI/CD pipelines and automation workflows.
Remote Scan Execution: Deploy and run the sensor via CLI on customer-managed infrastructure for scenarios such as:
1. Scanning air-gapped or internal instances the platform cannot directly reach
2. Customers wanting to manage their own scheduling and execution environment.

Refer to Sensors Architecture and Overview: Running the Sensor for additional execution and flow details.

Platform Scan Execution

Running the sensor through the user interface is the simplest and fastest way to get started. The platform enables running on-demand or scheduled scans in a dedicated environment.

Platform Scan Configuration

Step 1: Navigate to Sensors Setup Page

1.1 Open your browser and navigate to the Keyfactor AgileSec Platform Web URL

1.2 Log in with your credentials

1.3 Click on "Sensors" in the navigation bar.

Step 2: Select Artifactory Sensor

2.1 Click the "Choose a Sensor" button.

2.2 Browse or search for "Artifactory".

2.3 Click on the Artifactory sensor card.

This will open the sensor configuration interface.

Step 3: Configure Sensor Parameters

3.1 Fill in the required configuration parameters:

Platform Scan Configuration Fields

Field Name	Description
URL	Keyfactor URL instance, e.g. https://redacted.jfrog.io
Artifactory Token	API token retrieved from the Artifactory's UI, as shown in Supported Authentication Methods
Include and Exclude Patterns	Filter what repos in this Artifactory instance are scanned. This field uses a glob syntax, but for most cases the repos to scan can be stated plainly.
Repo and Package Type	Optionally state the type and package types included in the scan (e.g. LOCAL, YUM, respectively).
AQL Filter	Optional Artifactory query language filter. Example: `{"@license":{"$match":"GPL"},...}`. This filters over what files are downloaded within each repo.
Incremental Scan	Enable to scan only updates since last run. See Incremental Scanning
Auto-Resolution Interval	Number of scans before doing a full-scan. See Incremental Scanning

Scan Execution Using API

Scans may be programmatically triggered 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.

Note: For complete API reference, see the API document.

API Access Token

Open your browser and navigate to the AgileSec Platform UI.
Log in with your Keyfactor credentials.
Click "Access Tokens" in the main navigation menu.
Click "Generate Token".
Set Token Type to API Token and provide the required details.
Click "Generate" and copy the generated token.

API Endpoint

CODE

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

Request Format

Headers

CODE

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:

JSON

  {
    "sensorName": "<sensor name>",
    "sensorType": "JFROG Artifactory",
    "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 API Scan Configuration Fields section for details.

Remote Scan Execution

Remote Execution Flow allows you to run the sensor on a host using the Unified Sensor binary.

Remote Scan Execution Configuration

Step 1: Download Unified Sensor

1.1 Navigate to AgileSec Platform UI → Sensors → Remote Scan.

1.2 Download the sensor binary for your operating system.

Step 2: Generate Remote Sensor Token

2.1 In the Remote Scan UI, click "Generate Token".

2.2 Copy the generated token.

2.3 Store the token securely in an environment variable or set it in the sensor config:

BASH

  export SENSOR_TOKEN="your-generated-token"

Step 3: Create Configuration File

Create a YAML configuration file (e.g., artifactory-config.yml) with your scan settings. An example configuration can be found at config/sample-configs/artifactory.yml.

The configuration file contains the follow fields:

API Scan Configuration Fields

Field Name	Description
log_level	Optional log level. Example values: `"trace"`, `"debug"`, `"info"`, `"warn"`, `"error"`.
artifactory_url	Base URL of the Artifactory instance (e.g. `<https://redacted.jfrog.io`).>
artifactory_token	Access token generated in JFrog Artifactory, used for authentication.
threads	Optional number of download threads. Defaults to `5`.
batch_size_bytes	Advanced option. Limits cumulative disk usage per scan batch. If non-positive or unset, defaults to 50 GB. Content is scanned in batches not exceeding this limit and are deleted before proceeding. Does not account for archive decompression size; large single files exceeding the limit are skipped.
pre_extract	Advanced option. Defaults to `false`. If `true`, archives are extracted before scanning. Most findings can still be detected without pre-extraction.
insecure	Optional. If `true`, disables TLS certificate verification for the Artifactory instance.
include_repos	List of glob-style patterns for repositories to scan. Uses doublestar syntax: https://pkg.go.dev/github.com/bmatcuk/doublestar/v4
exclude_repos	Optional. Glob-style patterns for repositories to exclude. Takes precedence over `include_repos`.
repo_type	Optional. Restrict scanning to a specific Artifactory repository type (e.g. `LOCAL`). Remote repositories cannot be scanned directly; use a virtual repository instead.
repo_package_type	Optional. Restrict scanning to a specific Artifactory package type (e.g. `YUM`).
aql_extra_parameters	Optional AQL parameters used to further filter artifact files (e.g. `{ "@license": { "$match": "GPL" } }`).

Step 4: Run the Sensor

Run the sensor with your configuration file as shown:

BASH

./unified_sensor_linux -c ./my_config.yml

Troubleshooting

Remote Repositories

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

Forbidden Error (403)

Verify Read permissions on target repositories
Check permission target configuration
List accessible repos:

BASH

curl -H "Authorization: Bearer ${ARTIFACTORY_TOKEN}" \
https://company.jfrog.io/artifactory/api/repositories\
| jq '.[].key'

Empty Scan Target

Make sure to specify an include_pattern matching 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 API Scan Configuration Fields.

Getting Support

Collect diagnostic information:

Sensor version
Configuration file (redact tokens)
Log output
Artifactory version

Contact Support:

Portal: https://support.keyfactor.com