CI/CD Integration Guide for Kestrel

This guide shows how to integrate Kestrel into various CI/CD pipelines for automated cryptographic compliance scanning.

GitHub Actions
GitLab CI
Jenkins Pipeline
Azure DevOps
CircleCI
Docker Integration
Configuration Examples

GitHub Actions

Basic Integration

name: Security Scan
on: [push, pull_request]

jobs:
  crypto-audit:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - name: Run Kestrel
      run: |
        curl -L https://github.com/harekrishnarai/kestrel/releases/latest/download/kestrel-linux-amd64 -o kestrel
        chmod +x kestrel
        ./kestrel scan --path . --sarif --output results.sarif
    - name: Upload SARIF
      uses: github/codeql-action/upload-sarif@v2
      with:
        sarif_file: results.sarif

Advanced Integration with Multiple Formats

name: Comprehensive Security Audit
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  security-audit:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
      contents: read
      
    steps:
    - uses: actions/checkout@v4
    
    - name: Setup Kestrel
      run: |
        wget https://github.com/harekrishnarai/kestrel/releases/latest/download/kestrel-linux-amd64
        chmod +x kestrel-linux-amd64
        sudo mv kestrel-linux-amd64 /usr/local/bin/kestrel
        
    - name: Install Semgrep for multi-language support
      run: python3 -m pip install semgrep
      
    - name: Run Security Scan
      run: |
        mkdir -p reports
        kestrel scan \
          --path . \
          --frameworks fips_140_3,pci_dss_4 \
          --sarif \
          --output reports/security.sarif
          
        kestrel scan \
          --path . \
          --frameworks fips_140_3,pci_dss_4 \
          --html \
          --output reports/security-report.html \
          --html-charts \
          --html-theme light
          
        kestrel scan \
          --path . \
          --frameworks fips_140_3,pci_dss_4 \
          --pdf \
          --output reports/security-report.pdf \
          --pdf-title "Security Compliance Report" \
          --pdf-company "Your Organization"
          
    - name: Upload Security Results
      uses: github/codeql-action/upload-sarif@v2
      with:
        sarif_file: reports/security.sarif
        
    - name: Upload HTML Report
      uses: actions/upload-artifact@v3
      with:
        name: security-report
        path: reports/security-report.html
        
    - name: Fail on Critical Issues
      run: |
        if kestrel scan --path . --json | jq -r '.summary.critical' | grep -q -v '^0$'; then
          echo "Critical security issues found!"
          exit 1
        fi

GitLab CI

.gitlab-ci.yml

stages:
  - security

crypto_audit:
  stage: security
  image: ubuntu:22.04
  before_script:
    - apt-get update && apt-get install -y curl python3 python3-pip
    - python3 -m pip install semgrep
    - curl -L https://github.com/harekrishnarai/kestrel/releases/latest/download/kestrel-linux-amd64 -o kestrel
    - chmod +x kestrel
  script:
    - ./kestrel scan --path . --json --output crypto-audit.json
    - ./kestrel scan --path . --sarif --output crypto-audit.sarif
  artifacts:
    reports:
      sast: crypto-audit.sarif
    paths:
      - crypto-audit.json
      - crypto-audit.sarif
    expire_in: 1 week
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

# Generate HTML report for main branch
crypto_audit_html:
  stage: security
  image: ubuntu:22.04
  before_script:
    - apt-get update && apt-get install -y curl python3 python3-pip
    - python3 -m pip install semgrep
    - curl -L https://github.com/harekrishnarai/kestrel/releases/latest/download/kestrel-linux-amd64 -o kestrel
    - chmod +x kestrel
  script:
    - mkdir public
    - ./kestrel scan --path . --html --output public/security-report.html --html-charts
  artifacts:
    paths:
      - public/
    expire_in: 30 days
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

Jenkins Pipeline

Jenkinsfile

pipeline {
    agent any
    
    environment {
        KESTREL_VERSION = 'latest'
    }
    
    stages {
        stage('Setup') {
            steps {
                script {
                    // Download Kestrel
                    sh '''
                        curl -L https://github.com/harekrishnarai/kestrel/releases/latest/download/kestrel-linux-amd64 -o kestrel
                        chmod +x kestrel
                    '''
                    
                    // Install Semgrep
                    sh 'python3 -m pip install semgrep'
                }
            }
        }
        
        stage('Security Scan') {
            steps {
                script {
                    // Run Kestrel scan
                    sh '''
                        mkdir -p reports
                        ./kestrel scan \
                            --path . \
                            --frameworks fips_140_3,pci_dss_4 \
                            --json \
                            --output reports/crypto-audit.json
                            
                        ./kestrel scan \
                            --path . \
                            --frameworks fips_140_3,pci_dss_4 \
                            --html \
                            --output reports/security-dashboard.html \
                            --html-charts \
                            --html-theme light
                    '''
                }
            }
            
            post {
                always {
                    // Archive reports
                    archiveArtifacts artifacts: 'reports/*', fingerprint: true
                    
                    // Publish HTML report
                    publishHTML([
                        allowMissing: false,
                        alwaysLinkToLastBuild: true,
                        keepAll: true,
                        reportDir: 'reports',
                        reportFiles: 'security-dashboard.html',
                        reportName: 'Security Dashboard'
                    ])
                }
            }
        }
        
        stage('Policy Check') {
            steps {
                script {
                    // Check for critical violations
                    def exitCode = sh(
                        script: '''
                            CRITICAL=$(cat reports/crypto-audit.json | jq -r '.summary.critical // 0')
                            if [ "$CRITICAL" -gt "0" ]; then
                                echo "Critical violations found: $CRITICAL"
                                exit 1
                            fi
                            echo "No critical violations found"
                        ''',
                        returnStatus: true
                    )
                    
                    if (exitCode != 0) {
                        error("Critical security violations detected. Pipeline failed.")
                    }
                }
            }
        }
    }
    
    post {
        failure {
            emailext (
                subject: "Security Scan Failed: ${env.JOB_NAME} - ${env.BUILD_NUMBER}",
                body: "Critical cryptographic compliance violations detected. Please review the security dashboard.",
                to: "${env.CHANGE_AUTHOR_EMAIL}"
            )
        }
    }
}

Azure DevOps

azure-pipelines.yml

trigger:
  branches:
    include:
    - main
    - develop

pr:
  branches:
    include:
    - main

pool:
  vmImage: 'ubuntu-latest'

variables:
  kestrelVersion: 'latest'

stages:
- stage: SecurityScan
  displayName: 'Cryptographic Security Scan'
  jobs:
  - job: Kestrel
    displayName: 'Run Kestrel'
    steps:
    - task: UsePythonVersion@0
      inputs:
        versionSpec: '3.x'
        
    - script: |
        python -m pip install --upgrade pip semgrep
        curl -L https://github.com/harekrishnarai/kestrel/releases/latest/download/kestrel-linux-amd64 -o kestrel
        chmod +x kestrel
      displayName: 'Setup Tools'
      
    - script: |
        mkdir -p $(Build.ArtifactStagingDirectory)/reports
        ./kestrel scan \
          --path . \
          --frameworks fips_140_3,pci_dss_4 \
          --sarif \
          --output $(Build.ArtifactStagingDirectory)/reports/kestrel.sarif
          
        ./kestrel scan \
          --path . \
          --frameworks fips_140_3,pci_dss_4 \
          --json \
          --output $(Build.ArtifactStagingDirectory)/reports/kestrel.json
          
        ./kestrel scan \
          --path . \
          --frameworks fips_140_3,pci_dss_4 \
          --html \
          --output $(Build.ArtifactStagingDirectory)/reports/security-report.html \
          --html-charts
      displayName: 'Run Security Scan'
      
    - task: PublishBuildArtifacts@1
      inputs:
        pathToPublish: '$(Build.ArtifactStagingDirectory)/reports'
        artifactName: 'security-reports'
      displayName: 'Publish Security Reports'
      
    - script: |
        CRITICAL=$(cat $(Build.ArtifactStagingDirectory)/reports/kestrel.json | jq -r '.summary.critical // 0')
        if [ "$CRITICAL" -gt "0" ]; then
          echo "##vso[task.logissue type=error]Critical security violations found: $CRITICAL"
          exit 1
        fi
      displayName: 'Check Critical Violations'

CircleCI

.circleci/config.yml

version: 2.1

orbs:
  security: circleci/security@1.0

jobs:
  crypto-audit:
    docker:
      - image: cimg/python:3.9
    steps:
      - checkout
      
      - run:
          name: Install dependencies
          command: |
            pip install semgrep
            curl -L https://github.com/harekrishnarai/kestrel/releases/latest/download/kestrel-linux-amd64 -o kestrel
            chmod +x kestrel
            
      - run:
          name: Run Kestrel scan
          command: |
            mkdir -p reports
            ./kestrel scan \
              --path . \
              --frameworks fips_140_3,pci_dss_4 \
              --json \
              --output reports/crypto-audit.json
              
            ./kestrel scan \
              --path . \
              --frameworks fips_140_3,pci_dss_4 \
              --html \
              --output reports/security-report.html \
              --html-charts
              
      - store_artifacts:
          path: reports
          destination: security-reports
          
      - run:
          name: Check security policy
          command: |
            CRITICAL=$(cat reports/crypto-audit.json | jq -r '.summary.critical // 0')
            if [ "$CRITICAL" -gt "0" ]; then
              echo "Critical security violations found!"
              exit 1
            fi

workflows:
  security-scan:
    jobs:
      - crypto-audit:
          filters:
            branches:
              only:
                - main
                - develop

Docker Integration

Dockerfile for CI

FROM python:3.9-slim

# Install system dependencies
RUN apt-get update && \
    apt-get install -y curl && \
    rm -rf /var/lib/apt/lists/*

# Install Semgrep
RUN pip install semgrep

# Download Kestrel
RUN curl -L https://github.com/harekrishnarai/kestrel/releases/latest/download/kestrel-linux-amd64 -o /usr/local/bin/kestrel && \
    chmod +x /usr/local/bin/kestrel

# Set working directory
WORKDIR /workspace

# Entry point script
COPY scan-entrypoint.sh /usr/local/bin/
RUN chmod +x /usr/local/bin/scan-entrypoint.sh

ENTRYPOINT ["/usr/local/bin/scan-entrypoint.sh"]

scan-entrypoint.sh

#!/bin/bash
set -e

# Default values
SCAN_PATH=${SCAN_PATH:-"."}
OUTPUT_FORMAT=${OUTPUT_FORMAT:-"json"}
FRAMEWORKS=${FRAMEWORKS:-"fips_140_3"}
OUTPUT_FILE=${OUTPUT_FILE:-""}

echo "Kestrel Docker Scanner"
echo "Scan Path: $SCAN_PATH"
echo "Output Format: $OUTPUT_FORMAT"
echo "Frameworks: $FRAMEWORKS"

# Prepare output directory
mkdir -p /workspace/reports

# Build command
CMD="kestrel scan --path $SCAN_PATH --frameworks $FRAMEWORKS"

case $OUTPUT_FORMAT in
    "json")
        CMD="$CMD --json"
        OUTPUT_FILE=${OUTPUT_FILE:-"reports/kestrel.json"}
        ;;
    "sarif")
        CMD="$CMD --sarif"
        OUTPUT_FILE=${OUTPUT_FILE:-"reports/kestrel.sarif"}
        ;;
    "html")
        CMD="$CMD --html --html-charts"
        OUTPUT_FILE=${OUTPUT_FILE:-"reports/kestrel.html"}
        ;;
    *)
        # Default table format to stdout
        ;;
esac

if [ -n "$OUTPUT_FILE" ]; then
    CMD="$CMD --output $OUTPUT_FILE"
fi

echo "Running: $CMD"
eval $CMD

echo "Scan completed successfully"
if [ -n "$OUTPUT_FILE" ] && [ -f "$OUTPUT_FILE" ]; then
    echo "Report saved to: $OUTPUT_FILE"
fi

Docker Usage Examples

# Basic scan
docker run --rm -v $(pwd):/workspace kestrel:latest

# JSON output
docker run --rm -v $(pwd):/workspace -e OUTPUT_FORMAT=json kestrel:latest

# HTML report with custom path
docker run --rm -v $(pwd):/workspace \
  -e OUTPUT_FORMAT=html \
  -e SCAN_PATH=src/ \
  -e FRAMEWORKS=fips_140_3,pci_dss_4 \
  kestrel:latest

# SARIF for security platforms
docker run --rm -v $(pwd):/workspace \
  -e OUTPUT_FORMAT=sarif \
  -e OUTPUT_FILE=security.sarif \
  kestrel:latest

Configuration Examples

Policy Configuration (kestrel-policy.yml)

# Kestrel Policy Configuration
policy:
  name: "Corporate Security Policy"
  version: "1.0"
  
  enforcement:
    fail_on_critical: true
    fail_on_high: false
    max_high_violations: 5
    
  frameworks:
    - fips_140_3
    - pci_dss_4
    
  notifications:
    slack_webhook: "${SLACK_WEBHOOK_URL}"
    email_recipients:
      - security@company.com
      - devops@company.com
      
  reporting:
    generate_html: true
    html_theme: "light"
    include_charts: true
    retention_days: 90
    
  exemptions:
    # Temporary exemptions with expiry
    - algorithm: "SHA1"
      reason: "Legacy system migration in progress"
      expires: "2024-12-31"
      approved_by: "CISO"

Environment Configuration

# Environment variables for CI/CD
export KESTREL_FRAMEWORKS="fips_140_3,pci_dss_4"
export KESTREL_FAIL_ON_CRITICAL="true"
export KESTREL_FAIL_ON_HIGH="false"
export KESTREL_OUTPUT_FORMAT="sarif"
export KESTREL_HTML_THEME="dark"
export KESTREL_VERBOSE="true"

Best Practices

1. Pipeline Integration

Early Stage: Run Kestrel in early CI stages to catch issues quickly
Parallel Execution: Run alongside other security tools for comprehensive coverage
Fail Fast: Configure critical violations to fail the pipeline immediately

2. Report Management

Artifact Storage: Store reports as build artifacts for compliance documentation
GitHub Pages: Deploy HTML reports to GitHub Pages for easy access
SARIF Integration: Upload SARIF results to GitHub Security tab

3. Policy Enforcement

Graduated Response: Different severity levels trigger different actions
Exemption Process: Clear process for temporary exemptions with expiry
Notification Strategy: Alert relevant teams based on violation severity

4. Performance Optimization

Caching: Cache Kestrel binary and Semgrep rules
Incremental Scanning: Only scan changed files in large repositories
Parallel Jobs: Use matrix builds for multi-language projects

5. Monitoring and Metrics

Trend Analysis: Track violations over time
Compliance Metrics: Monitor compliance score trends
Alert Fatigue: Balance security with developer productivity

Troubleshooting

Common Issues

Semgrep Installation Failures

# Use specific Python version
python3.9 -m pip install semgrep

Permission Errors

# Ensure executable permissions
chmod +x kestrel

Memory Issues with Large Repositories

# Limit memory usage
kestrel scan --path . --semgrep-max-memory 2GB

Network Connectivity

# Pre-download in container builds
RUN curl -L https://github.com/.../kestrel-linux-amd64 -o kestrel

For more advanced configurations and enterprise features, see the Enterprise Integration Guide.

Table of Contents​

GitHub Actions​

Basic Integration​

Advanced Integration with Multiple Formats​

GitLab CI​

.gitlab-ci.yml​

Jenkins Pipeline​

Jenkinsfile​

Azure DevOps​

azure-pipelines.yml​

CircleCI​

.circleci/config.yml​

Docker Integration​

Dockerfile for CI​

scan-entrypoint.sh​

Docker Usage Examples​

Configuration Examples​

Policy Configuration (kestrel-policy.yml)​

Environment Configuration​

Best Practices​

1. Pipeline Integration​

2. Report Management​

3. Policy Enforcement​

4. Performance Optimization​

5. Monitoring and Metrics​

Troubleshooting​

Common Issues​

Table of Contents