SPECTRA on CybersecurityOS

Installation

Mon, 18 May 2026 00:00:00 +0000

Installation

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

System Requirements

Requirement	Minimum
Python	3.9+
pip	21.0+
Anthropic API key	Required (get one here)
Operating system	Linux, macOS, Windows (WSL2 recommended)
Memory	512 MB RAM minimum
Disk	100 MB for source + dependencies

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

Mon, 18 May 2026 00:00:00 +0000

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

Mon, 18 May 2026 00:00:00 +0000

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

Argument	Description
`INPUT`	Path to the scanner output file. Omit to read from stdin.

Options

Flag	Type	Default	Description
`--scanner`	string	auto	Force scanner type: `trivy`, `semgrep`, `generic`. Auto-detected from file structure when omitted.
`--format`	string	`markdown`	Output format: `markdown`, `json`, or `both`.
`--output`	string	`./spectra_report`	Output file path, without extension. SPECTRA appends `.md` and/or `.json` depending on `--format`.
`--usage`	flag	off	Print Anthropic API token usage stats after analysis. Useful for cost tracking.
`--model`	string	`claude-sonnet-4-6`	Claude model to use. See Configuration for supported models.
`--max-tokens`	int	4096	Maximum tokens for the AI response. Increase for very large scan files.
`--verbose`	flag	off	Enable verbose logging, including prompt and response details.

Examples

Configuration

Mon, 18 May 2026 00:00:00 +0000

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

Mon, 18 May 2026 00:00:00 +0000

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

Mon, 18 May 2026 00:00:00 +0000

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

Value	Files Generated	Use Case
`markdown` (default)	`<output>.md`	Reports, executive briefings, GRC documentation
`json`	`<output>.json`	SIEM integration, ticketing automation, dashboards
`both`	`<output>.md` + `<output>.json`	Full reporting + downstream automation

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

Mon, 18 May 2026 00:00:00 +0000

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

Inject ANTHROPIC_API_KEY as a repository secret — never hard-code credentials in pipeline YAML
Use --format json for machine-readable output and pipe to ticket creation or SIEM ingest
Use --format both to preserve a human-readable artifact for security team review
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

Platform	How to add `ANTHROPIC_API_KEY`
GitHub Actions	Settings → Secrets and variables → Actions → New repository secret
GitLab CI	Settings → CI/CD → Variables → Add variable
Jenkins	Manage Jenkins → Credentials → Add Credentials (Secret text)

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

Mon, 18 May 2026 00:00:00 +0000

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

Mon, 18 May 2026 00:00:00 +0000

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

Mon, 18 May 2026 00:00:00 +0000

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.

SPECTRA on CybersecurityOS

Installation

Installation

System Requirements

Option 1 — pip (Recommended)

Quick Start

Quick Start

Step 1 — Set your API key

Step 2 — Run your first analysis

CLI Reference

CLI Reference

Global Usage

Commands

spectra analyze

Configuration

Configuration

.env File

Supported Scanners

Supported Scanners

Trivy

Output Formats

Output Formats

Format Options

Markdown Report Structure

CI/CD Integration

CI/CD Integration

General Principles

GitHub Actions

Trivy + SPECTRA in a PR check

Semgrep + SPECTRA on push

GitLab CI

Jenkins (Declarative Pipeline)

Secrets Management

Recommended Pipeline Placement

Architecture

Architecture

High-Level Data Flow

Parser Layer

Contributing

Contributing to SPECTRA

Ways to Contribute

Getting Started

License

License and Legal Notices

Software License — Apache License 2.0

`spectra analyze`

`.env` File