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​