spektci 0.1.0

Multi-platform CI/CD compliance scanner for GitHub Actions, Jenkins, Bitbucket, Azure DevOps & CircleCI

CI/CD compliance scanner for GitHub Actions, Jenkins, Bitbucket, Azure DevOps & CircleCI

Quickstart • Controls • Configuration • CLI Reference • Contributing

---

🤔 What is spektci?

spektCI (from inspect + CI) is a multi-platform compliance scanner for CI/CD pipelines. It reads your pipeline configuration files and repository settings, then checks for security and compliance issues across 5 major CI/CD platforms.

What it detects:

• Container images using mutable tags (latest, dev)
• Secrets or credentials hardcoded in pipeline definitions
• Unprotected branches and missing branch policies
• Missing required security stages (SAST, SCA, secret scanning)
• Outdated or pinned-to-mutable-ref actions/orbs/plugins
• Overly permissive workflow permissions

🚀 Quickstart

# Install from GitHub
pip install git+https://github.com/OmarDakkak/spektCI.git

# Or clone and install locally
git clone https://github.com/OmarDakkak/spektCI.git
cd spektCI
pip install -e .

# Generate config
spektci config init

# Set token
export GITHUB_TOKEN=ghp_xxxx

# Run analysis
spektci analyze

See the full CLI Reference for all options.

🔍 Compliance Controls

ID	Control	What it catches
C001	Image Tags	node:latest instead of node:20.11.1
C002	Image Sources	Untrusted container registries
C003	Branch Protection	Missing PR reviews, force push allowed
C004	Hardcoded Secrets	Passwords / tokens in workflow files
C005	Pinned Actions	actions/checkout@main instead of a tag or SHA
C006	Required Stages	Missing SAST or secret scanning steps
C007	Permissions	permissions: write-all on workflows
C008	Outdated Deps	Actions multiple major versions behind

See docs/controls.md for detailed descriptions and configuration options.

🌐 Supported Platforms

Platform	Status
GitHub Actions	✅ Full support
Jenkins	🚧 Stub (planned)
Bitbucket Pipelines	🚧 Stub (planned)
Azure DevOps	🚧 Stub (planned)
CircleCI	🚧 Stub (planned)

See docs/adapters.md for adapter details.

💻 CLI Reference

# Auto-detect platform from git remote
spektci analyze

# Specify platform and repo explicitly
spektci analyze --platform github --repo owner/repo --branch main

# Set a custom compliance threshold (default: 80%)
spektci analyze --threshold 90

# Output as JSON or SARIF (for GitHub Security tab / SonarQube)
spektci analyze --format json --output report.json
spektci analyze --format sarif --output report.sarif

# Config management
spektci config init                        # Generate default .spektci.yaml
spektci config init --platform github      # Pre-configured for GitHub
spektci config view                        # Display effective config
spektci config validate                    # Validate config file

⚙️ Configuration

spektCI is configured via .spektci.yaml in your project root. Generate one with:

spektci config init

Key settings:

global:
  threshold: 80              # Minimum compliance % to pass
  fail_on: "error"           # Minimum severity to fail: error | warning | info
  output_format: "terminal"  # terminal | json | sarif

platform:
  type: auto                 # auto | github | jenkins | bitbucket | azure | circleci

controls:
  image_tags:
    enabled: true
    forbidden_tags: [latest, dev, main, master, staging]
  pinned_actions:
    enabled: true
    require_sha_pinning: false
  # ... see .spektci.yaml for all options

🧪 Development

# Setup
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Run tests (92 tests, 85% coverage)
pytest tests/ -v

# Lint + type check
ruff check src/ tests/
mypy src/spektci/

# Or use the Makefile
make all    # lint + typecheck + test

📄 License

MIT