Finite State Analysis

finitestate.io

The Finite State Analysis Jenkins Plugin provides multiple post-build actions for integrating with the Finite State platform. Each build step selects a Platform:

• Legacy Platform (Java CLT) — the default. Downloads and runs the Finite State Java CLT on the build agent, exactly as previous plugin versions did (requires Java on the agent). Use this if your organization is still on the legacy platform.
• 2026 Platform Release (REST API) — calls the Finite State public API (v0) directly over HTTPS. No CLT download and no Java required on the agent. Use this once your organization has been upgraded to the 2026 platform release.

Jobs saved before the Platform field existed default to Legacy Platform, so upgrading the plugin does not change their behavior. Select 2026 Platform Release to opt into the v0 REST API path.

This plugin gives you the ability to add Post Build actions and Pipeline steps for:

• Freestyle projects
• Multi-configuration projects
• Pipeline (Declarative and Scripted)

• Finite State Analyze Binary: Upload and analyze binary files (firmware images included — large files use the API's multipart upload automatically)
• Finite State Import SBOM: Import CycloneDX or SPDX SBOM files (format auto-detected)
• Finite State Import 3rd Party Scan: Import third-party scan results
• Per-step Platform selector: Legacy Platform (Java CLT, default) or 2026 Platform Release (public v0 REST API — no CLT download, no Java required on the agent)
• Secure credential management for API tokens
• Optionally waits for the scan to complete and sets the build result accordingly
• Logs the resolved project/version/scan IDs and a direct link to the results in the Finite State UI

To use this plugin, follow the following steps:

1. Install the plugin in your Jenkins instance.
2. Create or edit your Freestyle project or Multi-configuration project.
3. Click on the Add a Post-build Actions dropdown and select one of the Finite State options:
   • Finite State - Analyze Binary
   • Finite State - Import SBOM
   • Finite State - Import 3rd Party Scan
4. Generate an API Token: You need to generate an API token from your Finite State instance. Navigate to your Finite State domain (e.g., if your domain is fs-yolo.finitestate.io, go to https://fs-yolo.finitestate.io/settings/api-tokens) and generate a new API token. This token will be used to authenticate with the Finite State platform.
5. Complete the fields following the below reference. For sensitive fields like API Token, we use the credentials plugin, so be sure to create the text credential for this field and select the correct one on the dropdown.
6. In the Platform dropdown, choose Legacy Platform (Java CLT) (the default) if your organization is still on the legacy platform, or 2026 Platform Release (REST API) once your organization has been upgraded to the 2026 platform release. Leaving it at the default keeps existing jobs working unchanged after a plugin upgrade.

Uploads binary files to Finite State for comprehensive analysis.

Imports SBOM (Software Bill of Materials) files to Finite State for analysis.

Imports third-party scan results to Finite State for analysis.

1. Add any of the Finite State post-build actions to your Jenkins job
2. Configure the required fields for your chosen action
3. Run the build

The plugin will:

1. Resolve (or create) the project and version in Finite State by name — honoring the Pre-Release flag on version creation
2. Upload the artifact directly to Finite State storage and trigger processing (binary analysis, SBOM import, or third-party import)
3. Log the resolved project ID, version ID, scan ID(s), and a link to the results in the Finite State UI
4. By default, return success once the scan is submitted — you follow progress in the Finite State UI (the same flow the CLT used). Optionally enable "Wait for completion" to block until the scan reaches a terminal state and fail the build on a scan error or timeout

2026 platform release: all calls go to your instance's public API at https://<subdomain>/api/public/v0, authenticated with the X-Authorization header using the API token from the selected credential. The flow per run is: resolve project → resolve/create version → upload + trigger the scan → poll status (optional). No CLT is downloaded and nothing is executed as a subprocess; the upload runs on the build agent so artifact bytes never transit the Jenkins controller.

Legacy platform (default): the plugin downloads the Java CLT from https://<subdomain>/api/config/clt and runs it on the build agent (java -jar …), passing credentials via the FINITE_STATE_AUTH_TOKEN/FINITE_STATE_DOMAIN environment variables — the same behavior as plugin versions ≤ 1.092.

Upload mechanics differ by type:

• Binary uploads directly to storage (single PUT, or multipart for large firmware), then starts the scan.
• SBOM and third-party scans use the API's single-shot upload: the file is sent to the API, which stores it server-side and triggers processing in one call. This keeps scanner output (which often contains attack-signature strings) off a direct client→storage request that a WAF could block. Limitation: single-shot uploads are bounded by the API's request-body limit (a few MB), which is ample for typical SBOM/scanner files.

You can use these steps directly in Pipelines. The step names are the Jenkins symbols shown below.

• finiteStateAnalyzeBinary
• finiteStateImportSbom
• finiteStateImportThirdParty

• Analyze Binary

pipeline {
  agent any
  stages {
    stage('Finite State Binary Analysis') {
      steps {
        finiteStateAnalyzeBinary(
          platform: 'legacy', // 'legacy' = Legacy Platform (Java CLT, default); '2026' = 2026 Platform Release (REST API)
          subdomain: 'fs-your-subdomain.finitestate.io',
          apiTokenCredentialsId: 'your-jenkins-string-credentials-id',
          binaryFilePath: 'build/firmware.bin',
          projectName: 'My Project',
          projectVersion: '1.2.3',
          scaEnabled: true,
          sastEnabled: false,
          configEnabled: false,
          reachabilityEnabled: true,
          externalizableId: false,
          preRelease: false,
          waitForCompletion: false,
          pollTimeoutMinutes: 30
        )
      }
    }
  }
}

• Import SBOM

pipeline {
  agent any
  stages {
    stage('Finite State Import SBOM') {
      steps {
        finiteStateImportSbom(
          platform: 'legacy', // 'legacy' = Legacy Platform (Java CLT, default); '2026' = 2026 Platform Release (REST API)
          subdomain: 'fs-your-subdomain.finitestate.io',
          apiTokenCredentialsId: 'your-jenkins-string-credentials-id',
          sbomFilePath: 'sbom/cyclonedx.json',
          projectName: 'My Project',
          projectVersion: '1.2.3',
          externalizableId: false,
          preRelease: false,
          waitForCompletion: false,
          pollTimeoutMinutes: 30
        )
      }
    }
  }
}

• Import 3rd Party Scan

pipeline {
  agent any
  stages {
    stage('Finite State Import 3rd Party Scan') {
      steps {
        finiteStateImportThirdParty(
          platform: 'legacy', // 'legacy' = Legacy Platform (Java CLT, default); '2026' = 2026 Platform Release (REST API)
          subdomain: 'fs-your-subdomain.finitestate.io',
          apiTokenCredentialsId: 'your-jenkins-string-credentials-id',
          scanFilePath: 'reports/sonarqube.json',
          scanType: 'sonarqube_scan',
          projectName: 'My Project',
          projectVersion: '1.2.3',
          externalizableId: false,
          preRelease: false,
          waitForCompletion: false,
          pollTimeoutMinutes: 30
        )
      }
    }
  }
}

Notes:

• platform selects the transport and defaults to 'legacy' (Java CLT). Set platform: '2026' to use the public v0 REST API. It applies to all three steps, e.g. finiteStateAnalyzeBinary(platform: '2026', subdomain: '…', apiTokenCredentialsId: '…', …).

• Use apiTokenCredentialsId (the ID of a Secret Text credential containing your Finite State API token).

• If you set externalizableId: true, the step will use the Jenkins Run Externalizable ID as the project version. If externalizableId is false, projectVersion is required (the build fails with a clear message if both are empty).

• waitForCompletion (default false) returns as soon as the scan is submitted, logging the scan ID and UI link so you can follow progress in the Finite State UI. Set it to true to block until the scan reaches a terminal state and set the build result accordingly; pollTimeoutMinutes (default 30) bounds that wait. These optional fields apply to all three steps.

• For the scanType field in the finiteStateImportThirdParty step, you must select one of the supported scan types from the list in section Third-Party scanType values (exact identifiers) below. The value you provide should match exactly one of the identifiers in the "Third-Party scanType values" table. This ensures your scan is properly recognized and processed by the Finite State platform.

• These options are presented in the UI as four checkboxes: Binary SCA, Binary SAST, Configuration Analysis, and Reachability Analysis.

• At runtime the plugin maps the checkboxes onto the API's binary scan configuration:

  Checkbox	API BinaryScanConfig field
  Binary SCA	(always-on — see limitation below)
  Configuration Analysis	configurationAnalysis
  Reachability Analysis (requires SCA)	vulnerabilityAnalysis
  Binary SAST	binarySast

• SCA: Binary Software Composition Analysis. Limitation: the API always runs the binary SCA pass, so unchecking this box does not disable it; the checkbox is retained for configuration parity with earlier versions.

• SAST: Binary Static Application Security Testing

• Configuration Analysis: Configuration and security analysis

• Reachability Analysis: Performs reachability analysis on identified vulnerabilities (enabled by default, requires Binary SCA)

The plugin supports a comprehensive list of third-party scanning tools including:

Popular Tools:

• GitLab SAST/DAST/Container Scan: GitLab's built-in security scanning
• SonarQube: Code quality and security analysis
• Snyk: Vulnerability scanning for dependencies and containers
• Trivy: Container and infrastructure vulnerability scanner
• Semgrep: Static analysis for security and bugs
• Bandit: Python security linter
• Gosec: Go security linter
• ESLint: JavaScript/TypeScript linting with security rules

Cloud Security:

• AWS Prowler: AWS security assessment
• AWS Security Hub: AWS security findings
• Azure Security Center: Azure security recommendations
• Checkov: Infrastructure as Code security scanning

Container Security:

• Clair: Container vulnerability scanning
• Anchore: Container image analysis
• Twistlock: Container security platform

Dependency Scanning:

• Dependency Check: OWASP dependency vulnerability scanner
• Retire.js: JavaScript library vulnerability scanner
• NPM Audit: Node.js package vulnerability scanning
• Yarn Audit: Yarn package vulnerability scanning

And many more... including Acunetix, Burp Suite, Checkmarx, Fortify, Qualys, Tenable, Veracode, ZAP, and over 100 other supported tools.

For the complete list of supported tools and their expected file formats, refer to the dropdown in the Jenkins configuration.

Use these values for the scanType field in Pipelines (e.g., scanType: 'sonarqube_scan'). The left column is the UI label; the right column is the exact scanType identifier accepted by the step.

• Jenkins 2.479.3 or later
• Network access from the Jenkins controller and agents to your Finite State instance (https://<subdomain>)
• A Finite State API token with permission to read/create projects and versions, create scans, and read scan status

• API tokens are stored securely using Jenkins credentials and read only at execution time — never written to job config, build XML, or the console
• All API calls use HTTPS with the X-Authorization header; artifact uploads use short-lived presigned URLs
• No sensitive data is logged in the build output

Report issues and enhancements in the Github issue tracker.

Refer to our contribution guidelines

Licensed under MIT, see LICENSE

Please follow the steps described in the Developer Guide