Installation

SPECTRA runs anywhere Python 3.9+ is available. Three install paths are supported.

System Requirements

Option 1 — pip (Recommended)

git clone https://github.com/d0uble3L/spectra
cd spectra
pip install -e .

The -e flag installs in editable mode, making it easy to pull updates with git pull without reinstalling.

Quick Start

This guide gets you from install to your first analysis in under 5 minutes. It assumes you have already completed Installation.

Step 1 — Set your API key

cp .env.example .env
# Edit .env and add your Anthropic API key
ANTHROPIC_API_KEY=sk-ant-...

Step 2 — Run your first analysis

Use the bundled Trivy sample to confirm the setup:

spectra analyze tests/samples/trivy_sample.json

SPECTRA auto-detects the scanner type from the file structure and outputs a ranked summary to stdout.

CLI Reference

Complete reference for all SPECTRA commands and flags.

Global Usage

spectra [COMMAND] [OPTIONS] [INPUT]

Commands

spectra analyze

Analyze a scanner output file and produce ranked findings, attack chain analysis, and an executive summary.

spectra analyze [INPUT] [OPTIONS]

Arguments

Options

Examples

Configuration

SPECTRA is configured through a .env file in the project root and optionally through environment variables set in the shell or CI/CD pipeline.

.env File

Copy the template and populate your values:

cp .env.example .env

A complete .env file looks like this:

# Required
ANTHROPIC_API_KEY=sk-ant-...

# Optional — override defaults
SPECTRA_MODEL=claude-sonnet-4-6
SPECTRA_FORMAT=both
SPECTRA_OUTPUT=reports/latest
SPECTRA_MAX_TOKENS=4096

Never commit .env to version control. It is listed in .gitignore by default.

Supported Scanners

SPECTRA processes output from the following scanner types. Auto-detection is attempted by default; use --scanner to force a specific parser when auto-detection does not apply.

Trivy

Trivy is an open-source vulnerability scanner for containers, filesystems, Git repositories, and cloud infrastructure.

Auto-detected: Yes — from JSON structure
Input format: JSON (-f json)

Generate scan output:

# Container image scan
trivy image your-image:latest -f json -o trivy.json

# Filesystem scan
trivy fs . -f json -o trivy-fs.json

# Kubernetes scan
trivy k8s --report summary -f json -o trivy-k8s.json

Analyze with SPECTRA:

Output Formats

SPECTRA produces two output formats: Markdown (human-readable) and JSON (machine-readable for downstream tooling). Use --format both to generate both simultaneously.

Format Options

spectra analyze trivy.json --format both --output reports/scan-2026-05-18
# Writes: reports/scan-2026-05-18.md
#         reports/scan-2026-05-18.json

Markdown Report Structure

The Markdown report is structured for human review and is suitable for sharing directly with engineers, analysts, and leadership.

CI/CD Integration

SPECTRA’s CLI-first design makes it a natural fit in automated pipelines. This page covers integration patterns for GitHub Actions, GitLab CI, and Jenkins.

General Principles

1. Inject ANTHROPIC_API_KEY as a repository secret — never hard-code credentials in pipeline YAML
2. Use --format json for machine-readable output and pipe to ticket creation or SIEM ingest
3. Use --format both to preserve a human-readable artifact for security team review
4. Run SPECTRA after your scanner step, not before — it consumes scanner output, not raw code

GitHub Actions

Trivy + SPECTRA in a PR check

# .github/workflows/security-scan.yml
name: Security Scan

on:
  pull_request:
    branches: [main, develop]

jobs:
  spectra-analysis:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run Trivy container scan
        uses: aquasecurity/trivy-action@master
        with:
          image-ref: ${{ github.repository }}:${{ github.sha }}
          format: json
          output: trivy.json
          exit-code: 0

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Install SPECTRA
        run: |
          git clone https://github.com/d0uble3L/spectra /tmp/spectra
          pip install -e /tmp/spectra          

      - name: Run SPECTRA analysis
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          spectra analyze trivy.json --format both --output reports/pr-${{ github.event.pull_request.number }}          

      - name: Upload SPECTRA report
        uses: actions/upload-artifact@v4
        with:
          name: spectra-report-pr-${{ github.event.pull_request.number }}
          path: reports/
          retention-days: 30

Semgrep + SPECTRA on push

# .github/workflows/sast.yml
name: SAST

on:
  push:
    branches: [main]

jobs:
  sast:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run Semgrep
        run: |
          pip install semgrep
          semgrep --config=auto --json > semgrep.json          

      - name: Install SPECTRA
        run: |
          git clone https://github.com/d0uble3L/spectra /tmp/spectra
          pip install -e /tmp/spectra          

      - name: Run SPECTRA analysis
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          cat semgrep.json | spectra analyze --scanner semgrep --format both --output reports/sast-${{ github.run_id }}          

      - name: Upload report
        uses: actions/upload-artifact@v4
        with:
          name: spectra-sast-${{ github.run_id }}
          path: reports/

GitLab CI

# .gitlab-ci.yml
spectra-analysis:
  stage: security
  image: python:3.11-slim
  before_script:
    - apt-get update && apt-get install -y git
    - git clone https://github.com/d0uble3L/spectra /tmp/spectra
    - pip install -e /tmp/spectra
  script:
    - trivy image $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA -f json -o trivy.json
    - spectra analyze trivy.json --format both --output reports/pipeline-$CI_PIPELINE_ID
  artifacts:
    paths:
      - reports/
    expire_in: 30 days
  variables:
    ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY  # Set in GitLab CI/CD variables

Jenkins (Declarative Pipeline)

// Jenkinsfile
pipeline {
    agent any
    environment {
        ANTHROPIC_API_KEY = credentials('anthropic-api-key')
    }
    stages {
        stage('Trivy Scan') {
            steps {
                sh 'trivy image your-image:latest -f json -o trivy.json'
            }
        }
        stage('SPECTRA Analysis') {
            steps {
                sh '''
                    pip install -e /opt/spectra
                    spectra analyze trivy.json --format both --output reports/build-${BUILD_NUMBER}
                '''
            }
        }
    }
    post {
        always {
            archiveArtifacts artifacts: 'reports/**', allowEmptyArchive: true
        }
    }
}

Secrets Management

Recommended Pipeline Placement

Commit → Build → [ Trivy / Semgrep ] → SPECTRA → Report artifact → (optional) Ticket creation

SPECTRA runs after the scanner to analyze its output. It does not block the build by default — set your pipeline to fail on findings by parsing the JSON output for critical severity items if a gate is desired.

Architecture

This page covers SPECTRA’s internal design: how data flows through the system, how the AI layer works, and the key engineering decisions behind the implementation.

High-Level Data Flow

Scanner Output (Trivy JSON / Semgrep JSON / plain text)
        ↓
    Parser Layer
  (format detection + normalization)
        ↓
  Context Builder
  (finding enrichment + chain detection input)
        ↓
  Claude API (with prompt caching)
  (triage, attack chain analysis, executive summary)
        ↓
  Report Renderer
  (Markdown + JSON output)
        ↓
  Output Files / stdout

Parser Layer

SPECTRA includes a parser for each supported scanner format. Parsers normalize raw scanner output into a common internal schema before it reaches the AI layer:

Contributing to SPECTRA

SPECTRA is an open-source project and contributions are welcome. This page covers how to report issues, submit pull requests, and what to expect from the review process.

Ways to Contribute

• Bug reports — Found something broken? Open an issue on GitHub
• Feature requests — Have an idea? Open a discussion or issue with context on your use case
• New scanner parsers — SPECTRA currently supports Trivy, Semgrep, and generic. Adding a new parser is one of the highest-value contributions
• Documentation improvements — Clarifications, examples, and corrections are always welcome
• Test coverage — Additional test cases for edge cases in scanner parsing or output rendering
• Security vulnerability reports — See the Security Policy below

Getting Started

1. Fork and clone the repository:

License and Legal Notices

Software License — Apache License 2.0

SPECTRA is licensed under the Apache License, Version 2.0.

Copyright 2026 CybersecurityOS

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

The full license text is available at apache.org/licenses/LICENSE-2.0 and in the LICENSE file in the project repository.