CSPctl Documentation

# Initialize with secure defaults
cspctl init

# This creates csp.json with:
# - default-src: ['self']
# - script-src: ['self'] 
# - base-uri: ['none']
# - object-src: ['none']

# Launch the web UI on port 5173
cspctl ui

# Navigate to http://localhost:5173
# The UI provides:
# - Visual policy editor with syntax highlighting
# - Real-time validation
# - Directive documentation
# - Common pattern templates

# Run impact analysis
cspctl rollout dry-run --app myapp -f csp.json

# Example output:
# {
#   "blocked": 42,
#   "top_hosts": [
#     ["cdn.unauthorized.com", 21],
#     ["tracking.adnetwork.com", 10]
#   ],
#   "risky": ["'unsafe-inline' in script-src"]
# }

# Generate CSP header with strict-dynamic and nonce
cspctl header render -f csp.json --strict-dynamic

# Output example:
# default-src 'self'; script-src 'self' 'nonce-Nc3n83cnSAd' 'strict-dynamic'; 
# style-src 'self' 'unsafe-inline'; base-uri 'none'; object-src 'none'

# Step 1: Deploy to staging in report-only mode
cspctl policy push --app myapp-staging -f csp.json
cspctl rollout set --app myapp-staging --mode report-only --traffic 100

# Step 2: Monitor for 24-48 hours
cspctl reports --app myapp-staging --env prod
# Watch for unexpected violations

# Step 3: Analyze and adjust
cspctl policy suggest --app myapp-staging --env prod --export suggestions.json
# Review suggestions and update policy

# Step 4: Progressive production rollout
cspctl policy push --app myapp -f csp.json
cspctl rollout set --app myapp --mode enforce --traffic 10  # 10% of users
# Monitor for issues...
cspctl rollout set --app myapp --mode enforce --traffic 50  # 50% of users
# Continue monitoring...
cspctl rollout set --app myapp --mode enforce --traffic 100 # Full deployment

# Stream all violations as they happen
cspctl reports --app myapp --env prod

# Example output (grouped by directive):
# script-src: 42 violations
# img-src: 15 violations
# connect-src: 8 violations
# font-src: 2 violations

# Export full violation details (includes PII)
cspctl reports --app myapp --full --json > violations-full.json

# Analyze with jq
cat violations-full.json | jq '.[] | select(.blocked | contains("googleapis"))'

# Count unique blocked URIs
cat violations-full.json | jq -r '.blocked' | sort | uniq -c | sort -rn

# Get AI suggestions based on violations
cspctl policy suggest --app myapp --env prod

# Example suggestions:
# [
#   {
#     "directive": "script-src",
#     "source": "https://www.googletagmanager.com",
#     "confidence": 0.95,
#     "reason": "Consistent violations from analytics setup"
#   },
#   {
#     "directive": "font-src",
#     "source": "https://fonts.gstatic.com",
#     "confidence": 0.98,
#     "reason": "Google Fonts dependency detected"
#   }
# ]

# 1. Export current and suggested policies
cspctl policy pull --app myapp -f current.json
cspctl policy suggest --app myapp --export suggested.json

# 2. Review the differences
diff -u current.json suggested.json

# 3. Test the new policy impact
cspctl rollout dry-run --app myapp -f suggested.json

# 4. If safe (blocked count doesn't increase), apply changes
cspctl policy suggest --app myapp --apply
cspctl policy push --app myapp -f csp.json

# 5. Deploy with gradual rollout
cspctl rollout set --app myapp --mode enforce --traffic 10
# Monitor for new violations...
cspctl rollout set --app myapp --mode enforce --traffic 100

# Generate hashes for specific files
cspctl sri --path dist/js/app.js,dist/js/vendor.js --algo sha384

# Output:
# dist/js/app.js    sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC
# dist/js/vendor.js sha384-MBO9IDwOL7XdrMp3rJhiP3NOMJdUJ6pFmPwLgW2T7kE4qJphH0RTEgN8w7dGsqrQ

# Generate for all JS files with JSON output (for build automation)
cspctl sri --path "dist/**/*.js" --algo sha384 --json > sri-hashes.json

# Generate multiple algorithm hashes (for fallback support)
cspctl sri --path dist/critical.js --algo sha256,sha384,sha512

# Output:
# dist/critical.js sha256-RmX... sha384-oqV... sha512-9/u...

// webpack.config.js - Webpack SRI Plugin
const { SubresourceIntegrityPlugin } = require('webpack-subresource-integrity');

module.exports = {
  output: {
    crossOriginLoading: 'anonymous',
  },
  plugins: [
    new SubresourceIntegrityPlugin({
      hashFuncNames: ['sha384'],
      enabled: process.env.NODE_ENV === 'production',
    }),
  ],
};

// build.js - Custom build script
const { execSync } = require('child_process');
const fs = require('fs');

// Generate SRI hashes after build
const sriOutput = execSync(
  'cspctl sri --path dist/**/*.js --algo sha384 --json'
).toString();

const sriHashes = JSON.parse(sriOutput);

// Update HTML templates with SRI hashes
let html = fs.readFileSync('dist/index.html', 'utf8');
for (const [file, hash] of Object.entries(sriHashes)) {
  const filename = file.split('/').pop();
  html = html.replace(
    new RegExp(`src="[^"]*${filename}"`, 'g'),
    `src="/${file}" integrity="${hash}" crossorigin="anonymous"`
  );
}
fs.writeFileSync('dist/index.html', html);

// sri-monitor.js - Monitor for SRI failures
window.addEventListener('error', (e) => {
  if (e.target && e.target.integrity) {
    // SRI failure detected
    console.error('SRI failure:', e.target.src || e.target.href);
    
    // Report to monitoring service
    fetch('/api/sri-failure', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        resource: e.target.src || e.target.href,
        integrity: e.target.integrity,
        timestamp: new Date().toISOString(),
        userAgent: navigator.userAgent,
      }),
    });
    
    // Attempt fallback if configured
    const fallbackUrl = e.target.dataset.fallback;
    if (fallbackUrl) {
      const newElement = e.target.cloneNode();
      newElement.src = fallbackUrl;
      newElement.integrity = e.target.dataset.fallbackIntegrity;
      e.target.parentNode.replaceChild(newElement, e.target);
    }
  }
}, true);

# Prepare for offline work - cache all environments
for env in dev staging prod; do
  echo "Caching $env environment..."
  cspctl policy pull --app myapp --env $env -f /tmp/cache-$env.json
  cspctl reports --app myapp --env $env --limit 1000 --json > /dev/null
done

# Verify cache is populated
ls -la ~/.cspctl/cache/myapp/
# dev/
# staging/
# prod/

# Check cache freshness
find ~/.cspctl/cache -name ".timestamp" -exec sh -c 'echo "{}:"; cat {}' \;
# Shows when each cache was last updated

#!/bin/bash
# offline-dev.sh - Complete offline development workflow

# 1. Create development policy from cache
cspctl policy pull --app myapp --env prod -f base.json --offline
cp base.json dev-policy.json

# 2. Modify policy locally
cat dev-policy.json | jq '.directives."script-src" += ["https://new-cdn.com"]' > dev-policy.json

# 3. Validate changes
cspctl policy validate -f dev-policy.json

# 4. Simulate impact using cached violation data
echo "Analyzing policy impact..."
CACHED_REPORTS=$(cat ~/.cspctl/cache/myapp/prod/reports.json)
NEW_BLOCKS=$(echo "$CACHED_REPORTS" | jq '[.[] | select(.blocked_uri | contains("new-cdn.com"))] | length')
echo "Policy would block $NEW_BLOCKS additional requests"

# 5. Generate deployment artifacts
cspctl header render -f dev-policy.json > headers.txt
cspctl policy format -f dev-policy.json > formatted-policy.json

# 6. Create rollout plan
cat > rollout-plan.md << EOF
## Rollout Plan
- Changes: Added new-cdn.com to script-src
- Estimated impact: $NEW_BLOCKS blocks
- Deployment stages:
  1. Deploy to staging (report-only)
  2. Monitor for 24h
  3. Deploy to prod at 10% traffic
  4. Gradual increase to 100%
EOF

echo "✅ Offline development complete. Ready to sync when online."

# Check connectivity status
cspctl status
# API: ✅ Connected
# Cache: 3 days old
# Pending changes: 1 policy update

# Push offline changes
cspctl policy push --app myapp -f dev-policy.json
# ✅ Policy updated successfully

# Refresh cache with latest data
cspctl cache refresh --app myapp --all-envs
# Refreshing cache for all environments...
# ✅ Cache updated (dev, staging, prod)

# Verify sync status
cspctl cache status
# myapp/dev: Fresh (< 1 minute)
# myapp/staging: Fresh (< 1 minute)
# myapp/prod: Fresh (< 1 minute)

name: CSP Pipeline

on:
  pull_request:
    paths:
      - 'csp.json'
      - 'src/**'
      - 'public/**'
  push:
    branches: [main, staging]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install CSPctl
        run: |
          curl -fsSL https://install.cspctl.com/install.sh | sh
          echo "$HOME/.cspctl/bin" >> $GITHUB_PATH
      
      - name: Validate Policy Syntax
        run: |
          cspctl policy validate -f csp.json
          echo "✅ Policy syntax valid"
      
      - name: Check for Risky Directives
        run: |
          RISKY=$(cspctl policy analyze -f csp.json --json | jq '.risky | length')
          if [ "$RISKY" -gt 0 ]; then
            echo "⚠️ Policy contains risky directives:"
            cspctl policy analyze -f csp.json --json | jq '.risky'
            exit 1
          fi
      
      - name: Generate SRI Hashes
        run: |
          cspctl sri --path dist/**/*.js --algo sha384 --json > sri-hashes.json
          echo "Generated SRI hashes for $(jq 'length' sri-hashes.json) files"
      
      - name: Upload Artifacts
        uses: actions/upload-artifact@v3
        with:
          name: csp-artifacts
          path: |
            csp.json
            sri-hashes.json

  impact-analysis:
    runs-on: ubuntu-latest
    needs: validate
    if: github.event_name == 'pull_request'
    steps:
      - uses: actions/checkout@v3
      
      - name: Install CSPctl
        run: |
          curl -fsSL https://install.cspctl.com/install.sh | sh
          echo "$HOME/.cspctl/bin" >> $GITHUB_PATH
      
      - name: Configure CSPctl
        env:
          CSPCTL_API_KEY: ${{ secrets.CSPCTL_API_KEY }}
        run: |
          cspctl auth login --api-key $CSPCTL_API_KEY
      
      - name: Run Dry-Run Analysis
        id: dryrun
        run: |
          OUTPUT=$(cspctl rollout dry-run --app ${{ vars.APP_ID }} -f csp.json --json)
          echo "blocked=$(echo $OUTPUT | jq '.blocked')" >> $GITHUB_OUTPUT
          echo "allowed=$(echo $OUTPUT | jq '.allowed')" >> $GITHUB_OUTPUT
          echo "impact=$(echo $OUTPUT | jq '.impact_percentage')" >> $GITHUB_OUTPUT
      
      - name: Generate AI Suggestions
        run: |
          cspctl policy suggest --app ${{ vars.APP_ID }} --env staging --json > suggestions.json
          
      - name: Comment PR with Analysis
        uses: actions/github-script@v6
        with:
          script: |
            const blocked = ${{ steps.dryrun.outputs.blocked }};
            const allowed = ${{ steps.dryrun.outputs.allowed }};
            const impact = ${{ steps.dryrun.outputs.impact }};
            
            const comment = `## 🔒 CSP Impact Analysis
            
            ### Dry-Run Results
            - **Blocked Requests**: ${blocked}
            - **Allowed Requests**: ${allowed}
            - **Impact**: ${impact}% of traffic affected
            
            ### Recommendations
            ${blocked > 100 ? '⚠️ High impact detected. Review blocked resources carefully.' : '✅ Low impact. Safe to proceed.'}
            
            <details>
            <summary>View AI Suggestions</summary>
            
            \`\`\`json
            ${require('fs').readFileSync('suggestions.json', 'utf8')}
            \`\`\`
            </details>`;
            
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: comment
            });

  deploy-staging:
    runs-on: ubuntu-latest
    needs: [validate, impact-analysis]
    if: github.ref == 'refs/heads/staging'
    environment: staging
    steps:
      - uses: actions/checkout@v3
      
      - name: Deploy to Staging
        env:
          CSPCTL_API_KEY: ${{ secrets.CSPCTL_API_KEY }}
        run: |
          cspctl auth login --api-key $CSPCTL_API_KEY
          
          # Deploy in report-only mode
          cspctl policy push --app ${{ vars.APP_ID }} --env staging -f csp.json
          cspctl rollout set --app ${{ vars.APP_ID }} --env staging \
            --mode report-only --traffic 100
          
          echo "✅ Deployed to staging in report-only mode"
      
      - name: Monitor Initial Violations
        run: |
          sleep 60  # Wait for initial data
          cspctl reports --app ${{ vars.APP_ID }} --env staging \
            --limit 100 --json > staging-violations.json
          
          VIOLATION_COUNT=$(jq 'length' staging-violations.json)
          echo "📊 Initial violations: $VIOLATION_COUNT"

  deploy-production:
    runs-on: ubuntu-latest
    needs: validate
    if: github.ref == 'refs/heads/main'
    environment: production
    strategy:
      max-parallel: 1
    steps:
      - uses: actions/checkout@v3
      
      - name: Progressive Rollout
        env:
          CSPCTL_API_KEY: ${{ secrets.CSPCTL_API_KEY }}
        run: |
          cspctl auth login --api-key $CSPCTL_API_KEY
          
          # Stage 1: 10% traffic
          echo "🚀 Stage 1: Deploying to 10% of traffic..."
          cspctl policy push --app ${{ vars.APP_ID }} --env prod -f csp.json
          cspctl rollout set --app ${{ vars.APP_ID }} --env prod \
            --mode enforce --traffic 10
          
          # Monitor for 5 minutes
          sleep 300
          VIOLATIONS_10=$(cspctl reports --app ${{ vars.APP_ID }} --env prod \
            --limit 100 --json | jq 'length')
          
          if [ "$VIOLATIONS_10" -gt 50 ]; then
            echo "❌ Too many violations at 10%. Rolling back..."
            cspctl rollout set --app ${{ vars.APP_ID }} --env prod \
              --mode report-only --traffic 100
            exit 1
          fi
          
          # Stage 2: 50% traffic
          echo "🚀 Stage 2: Expanding to 50% of traffic..."
          cspctl rollout set --app ${{ vars.APP_ID }} --env prod \
            --mode enforce --traffic 50
          
          sleep 300
          VIOLATIONS_50=$(cspctl reports --app ${{ vars.APP_ID }} --env prod \
            --limit 100 --json | jq 'length')
          
          if [ "$VIOLATIONS_50" -gt 100 ]; then
            echo "❌ Too many violations at 50%. Rolling back..."
            cspctl rollout set --app ${{ vars.APP_ID }} --env prod \
              --mode enforce --traffic 10
            exit 1
          fi
          
          # Stage 3: 100% traffic
          echo "🚀 Stage 3: Full deployment..."
          cspctl rollout set --app ${{ vars.APP_ID }} --env prod \
            --mode enforce --traffic 100
          
          echo "✅ Successfully deployed to production"

pipeline {
    agent any
    
    environment {
        CSPCTL_API_KEY = credentials('cspctl-api-key')
        APP_ID = 'myapp'
    }
    
    stages {
        stage('Setup') {
            steps {
                sh '''
                    curl -fsSL https://install.cspctl.com/install.sh | sh
                    export PATH="$HOME/.cspctl/bin:$PATH"
                    cspctl auth login --api-key $CSPCTL_API_KEY
                '''
            }
        }
        
        stage('Validate') {
            steps {
                script {
                    def validation = sh(
                        script: 'cspctl policy validate -f csp.json',
                        returnStatus: true
                    )
                    
                    if (validation != 0) {
                        error('Policy validation failed')
                    }
                    
                    // Check for unsafe directives
                    def unsafe = sh(
                        script: "grep -E 'unsafe-inline|unsafe-eval' csp.json",
                        returnStatus: true
                    )
                    
                    if (unsafe == 0) {
                        unstable('Policy contains unsafe directives')
                    }
                }
            }
        }
        
        stage('Impact Analysis') {
            when {
                changeRequest()
            }
            steps {
                script {
                    def dryRun = sh(
                        script: "cspctl rollout dry-run --app ${APP_ID} -f csp.json --json",
                        returnStdout: true
                    ).trim()
                    
                    def parsed = readJSON text: dryRun
                    
                    if (parsed.blocked > 100) {
                        currentBuild.description = "⚠️ High impact: ${parsed.blocked} blocks"
                        unstable('High CSP impact detected')
                    } else {
                        currentBuild.description = "✅ Low impact: ${parsed.blocked} blocks"
                    }
                    
                    // Archive analysis
                    writeFile file: 'dry-run-analysis.json', text: dryRun
                    archiveArtifacts artifacts: 'dry-run-analysis.json'
                }
            }
        }
        
        stage('Generate SRI') {
            steps {
                sh '''
                    cspctl sri --path dist/**/*.js --algo sha384 --json > sri-hashes.json
                    echo "Generated SRI hashes for:"
                    jq -r 'keys[]' sri-hashes.json
                '''
                archiveArtifacts artifacts: 'sri-hashes.json'
            }
        }
        
        stage('Deploy') {
            when {
                branch 'main'
            }
            steps {
                script {
                    // Deploy with monitoring
                    sh """
                        cspctl policy push --app ${APP_ID} --env prod -f csp.json
                        cspctl rollout set --app ${APP_ID} --env prod \
                          --mode report-only --traffic 100
                    """
                    
                    // Wait and check violations
                    sleep(time: 5, unit: 'MINUTES')
                    
                    def violations = sh(
                        script: "cspctl reports --app ${APP_ID} --env prod --json | jq 'length'",
                        returnStdout: true
                    ).trim().toInteger()
                    
                    if (violations < 50) {
                        sh """
                            cspctl rollout set --app ${APP_ID} --env prod \
                              --mode enforce --traffic 10
                        """
                        echo "Deployed to 10% of production traffic"
                    } else {
                        error("Too many violations: ${violations}")
                    }
                }
            }
        }
    }
    
    post {
        failure {
            emailext(
                subject: "CSP Pipeline Failed: ${env.JOB_NAME} - ${env.BUILD_NUMBER}",
                body: "Policy deployment failed. Check violations at ${env.BUILD_URL}",
                to: 'security-team@example.com'
            )
        }
        success {
            slackSend(
                color: 'good',
                message: "CSP deployed successfully to ${env.BRANCH_NAME}"
            )
        }
    }
}

.gitlab-ci.yml

variables:
  APP_ID: "myapp"
  CSPCTL_VERSION: "latest"

stages:
  - validate
  - test
  - deploy

before_script:
  - curl -fsSL https://install.cspctl.com/install.sh | sh
  - export PATH="$HOME/.cspctl/bin:$PATH"
  - cspctl auth login --api-key $CSPCTL_API_KEY

# Cache CSPctl installation
cache:
  key: cspctl-${CSPCTL_VERSION}
  paths:
    - $HOME/.cspctl/

validate:policy:
  stage: validate
  script:
    - cspctl policy validate -f csp.json
    - |
      if grep -E 'unsafe-inline|unsafe-eval' csp.json; then
        echo "⚠️ Policy contains unsafe directives"
        exit 1
      fi
  artifacts:
    reports:
      dotenv: csp-validation.env

test:dry-run:
  stage: test
  script:
    - |
      OUTPUT=$(cspctl rollout dry-run --app $APP_ID -f csp.json --json)
      BLOCKED=$(echo $OUTPUT | jq '.blocked')
      echo "CSP_BLOCKED=$BLOCKED" >> impact.env
      
      if [ "$BLOCKED" -gt 100 ]; then
        echo "❌ High impact: $BLOCKED blocks expected"
        exit 1
      fi
  artifacts:
    reports:
      dotenv: impact.env
    paths:
      - dry-run-report.json

test:sri:
  stage: test
  parallel:
    matrix:
      - ALGO: [sha256, sha384, sha512]
  script:
    - cspctl sri --path dist/**/*.js --algo $ALGO --json > sri-$ALGO.json
  artifacts:
    paths:
      - sri-*.json

deploy:staging:
  stage: deploy
  environment:
    name: staging
    url: https://staging.example.com
  only:
    - staging
  script:
    - cspctl policy push --app $APP_ID --env staging -f csp.json
    - cspctl rollout set --app $APP_ID --env staging --mode report-only --traffic 100
    - echo "✅ Deployed to staging"

deploy:production:
  stage: deploy
  environment:
    name: production
    url: https://example.com
  only:
    - main
  when: manual
  script:
    - |
      # Progressive rollout with health checks
      for TRAFFIC in 10 50 100; do
        echo "🚀 Rolling out to $TRAFFIC% of traffic..."
        cspctl rollout set --app $APP_ID --env prod --mode enforce --traffic $TRAFFIC
        
        sleep 300  # 5 minutes
        
        VIOLATIONS=$(cspctl reports --app $APP_ID --env prod --json | jq 'length')
        if [ "$VIOLATIONS" -gt $((TRAFFIC * 2)) ]; then
          echo "❌ Rollback triggered: $VIOLATIONS violations"
          cspctl rollout set --app $APP_ID --env prod --mode report-only --traffic 100
          exit 1
        fi
      done
      
      echo "✅ Full production deployment complete"

#!/bin/bash
# monitor-csp.sh - Continuous monitoring script

set -e

# Configuration
THRESHOLD_CRITICAL=100
THRESHOLD_WARNING=50
CHECK_INTERVAL=300  # 5 minutes
SLACK_WEBHOOK=$SLACK_CSP_WEBHOOK

monitor_violations() {
    local env=$1
    local violations=$(cspctl reports --app $APP_ID --env $env --json | jq 'length')
    local unique_hosts=$(cspctl reports --app $APP_ID --env $env --group-by host --json | jq 'length')
    
    echo "[$(date)] $env: $violations violations from $unique_hosts hosts"
    
    if [ "$violations" -gt "$THRESHOLD_CRITICAL" ]; then
        alert_critical "$env" "$violations" "$unique_hosts"
    elif [ "$violations" -gt "$THRESHOLD_WARNING" ]; then
        alert_warning "$env" "$violations" "$unique_hosts"
    fi
    
    # Log metrics for dashboards
    echo "csp.violations.$env:$violations|g" | nc -u -w0 127.0.0.1 8125
    echo "csp.unique_hosts.$env:$unique_hosts|g" | nc -u -w0 127.0.0.1 8125
}

alert_critical() {
    local env=$1
    local violations=$2
    local hosts=$3
    
    # Send Slack alert
    curl -X POST $SLACK_WEBHOOK -H 'Content-Type: application/json' -d "{
        "text": "🚨 Critical CSP Alert",
        "attachments": [{
            "color": "danger",
            "fields": [
                {"title": "Environment", "value": "$env", "short": true},
                {"title": "Violations", "value": "$violations", "short": true},
                {"title": "Unique Hosts", "value": "$hosts", "short": true},
                {"title": "Action", "value": "Immediate review required", "short": true}
            ]
        }]
    }"
    
    # Trigger automatic rollback if in production
    if [ "$env" = "prod" ]; then
        echo "Triggering automatic rollback..."
        cspctl rollout set --app $APP_ID --env prod --mode report-only --traffic 100
    fi
}

# Main monitoring loop
while true; do
    for env in staging prod; do
        monitor_violations $env
    done
    
    sleep $CHECK_INTERVAL
done