Skip to main content

Jenkins Plugin

Integrate CXRay security scanning into your Jenkins CI/CD pipelines.

Installation​

Via Jenkins Plugin Manager​

  1. Navigate to Manage Jenkins → Manage Plugins
  2. Go to the Available tab
  3. Search for "CXRay Security Scanner"
  4. Select the plugin and click Install without restart

Manual Installation​

  1. Download the latest .hpi file from the CXRay Jenkins Plugin releases
  2. Navigate to Manage Jenkins → Manage Plugins → Advanced
  3. Upload the .hpi file under Upload Plugin
  4. Restart Jenkins when safe

Configuration​

Global Configuration​

  1. Go to Manage Jenkins → Configure System
  2. Scroll to CXRay Configuration
  3. Configure the following settings:
CXRay API URL: https://api.cxray.io
API Key: [Your API Key]
Database Update Frequency: Daily

Credentials Setup​

Store your CXRay API key securely:

  1. Navigate to Manage Jenkins → Manage Credentials
  2. Add a Secret text credential
  3. Enter your CXRay API key
  4. Set ID as cxray-api-key

Pipeline Integration​

Declarative Pipeline​

pipeline {
    agent any

    stages {
        stage('Checkout') {
            steps {
                checkout scm
            }
        }

        stage('Build') {
            steps {
                sh 'npm install'
                sh 'npm run build'
            }
        }

        stage('CXRay Security Scan') {
            steps {
                cxrayScan(
                    scanTypes: ['cve', 'cce', 'sbom'],
                    severity: 'high,critical',
                    failOnSeverity: 'critical',
                    outputFormat: 'json',
                    generateReport: true
                )
            }
        }
    }

    post {
        always {
            // Archive scan results
            archiveArtifacts artifacts: 'cxray-*.json', allowEmptyArchive: true

            // Publish HTML report
            publishHTML([
                reportDir: 'cxray-reports',
                reportFiles: 'index.html',
                reportName: 'CXRay Security Report'
            ])
        }
    }
}

Scripted Pipeline​

node {
    stage('Checkout') {
        checkout scm
    }

    stage('Build') {
        sh 'npm install'
        sh 'npm run build'
    }

    stage('CXRay Scan') {
        def scanResult = cxrayScan(
            scanTypes: ['cve', 'sbom'],
            severity: 'all',
            outputFormat: 'json'
        )

        // Check scan results
        if (scanResult.criticalCount > 0) {
            error("Critical vulnerabilities found: ${scanResult.criticalCount}")
        }
    }
}

Freestyle Project​

  1. Create or configure a Freestyle project
  2. Add a Build Step → CXRay Security Scan
  3. Configure scan options:
Scan Types: CVE, CCE, SBOM
Severity Filter: high,critical
Fail Build On: critical
Output Format: JSON
Generate HTML Report: Yes

Configuration Options​

Scan Types​

  • CVE: Vulnerability scanning
  • CCE: Configuration scanning
  • SBOM: Software Bill of Materials generation

Severity Filters​

  • all: All severities
  • critical: Critical only
  • high,critical: High and Critical
  • medium,high,critical: Medium and above

Fail Conditions​

Configure when the build should fail:

cxrayScan(
    failOnSeverity: 'critical',        // Fail on critical findings
    failOnCVSS: 9.0,                   // Fail on CVSS >= 9.0
    failOnCount: [critical: 1, high: 5] // Fail on count thresholds
)

Advanced Features​

Scan Specific Paths​

cxrayScan(
    scanPath: 'src/',
    excludePaths: ['node_modules/', 'test/']
)

Custom Configuration​

cxrayScan(
    configFile: 'custom-cxray.yml',
    customRules: 'jenkins-rules/'
)

Differential Scanning​

Only scan changed files:

cxrayScan(
    differential: true,
    baseCommit: env.GIT_PREVIOUS_COMMIT
)

Report Generation​

HTML Report​

cxrayScan(
    generateReport: true,
    reportFormat: 'html',
    reportOutput: 'cxray-report/'
)

publishHTML([
    reportDir: 'cxray-report',
    reportFiles: 'index.html',
    reportName: 'CXRay Security Report',
    keepAll: true
])

SARIF for GitHub Integration​

cxrayScan(
    outputFormat: 'sarif',
    reportOutput: 'results.sarif'
)

// Upload to GitHub Code Scanning
sh 'gh api repos/${REPO}/code-scanning/sarifs -f sarif=@results.sarif'

Multiple Output Formats​

cxrayScan(
    outputs: [
        [format: 'json', file: 'cxray.json'],
        [format: 'html', file: 'report.html'],
        [format: 'sarif', file: 'results.sarif'],
        [format: 'csv', file: 'findings.csv']
    ]
)

Notifications​

Email Notifications​

post {
    failure {
        emailext(
            subject: "CXRay Scan Failed: ${env.JOB_NAME}",
            body: "Critical vulnerabilities found in build ${env.BUILD_NUMBER}",
            to: 'security-team@example.com',
            attachmentsPattern: 'cxray-report.html'
        )
    }
}

Slack Notifications​

post {
    always {
        script {
            def scanResult = readJSON file: 'cxray-results.json'
            slackSend(
                channel: '#security-alerts',
                color: scanResult.criticalCount > 0 ? 'danger' : 'good',
                message: "CXRay Scan: ${scanResult.criticalCount} critical, ${scanResult.highCount} high vulnerabilities"
            )
        }
    }
}

Troubleshooting​

Plugin Not Scanning​

Check the following:

  1. API key is correctly configured
  2. Network connectivity to CXRay API
  3. Sufficient disk space for database
  4. Project contains supported package managers

Build Failing Unexpectedly​

// Add verbose logging
cxrayScan(
    verbose: true,
    logLevel: 'debug'
)

Database Update Issues​

Force database update:

cxrayScan(
    updateDatabase: true,
    forceUpdate: true
)

Best Practices​

  1. Run Early: Execute CXRay scans early in the pipeline
  2. Cache Database: Cache the vulnerability database between builds
  3. Set Thresholds: Define clear failure thresholds
  4. Archive Results: Always archive scan results as artifacts
  5. Monitor Trends: Track vulnerability trends over time
  6. Incremental Scans: Use differential scanning for large projects

Next Steps​