Metadata-Version: 2.4
Name: cyfendo
Version: 2.0.3
Summary: Lightweight CLI scanner and sovereign BYOM engine for the Cyfendo Autonomous Security Platform
Author-email: Cyfendo Security Team <contact@cyfendo.com>
License: MIT
Project-URL: Homepage, https://cyfendo.com
Project-URL: Documentation, https://cyfendo.com/docs
Project-URL: Developer Settings, https://cyfendo.com/settings/developer
Keywords: security,sast,vulnerability-scanner,appsec,cyfendo,patching,byom
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: certifi>=2024.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: google-genai>=0.1.1
Requires-Dist: openai>=1.0.0
Requires-Dist: anthropic>=0.18.0
Provides-Extra: byom
Requires-Dist: google-genai>=0.1.1; extra == "byom"
Requires-Dist: openai>=1.0.0; extra == "byom"
Requires-Dist: anthropic>=0.18.0; extra == "byom"
Provides-Extra: gemini
Requires-Dist: google-genai>=0.1.1; extra == "gemini"
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.18.0; extra == "anthropic"

# Cyfendo CLI 🛡️

[![PyPI version](https://img.shields.io/pypi/v/cyfendo.svg)](https://pypi.org/project/cyfendo/)
[![Python Version](https://img.shields.io/pypi/pyversions/cyfendo.svg)](https://pypi.org/project/cyfendo/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

> **Autonomous Application Security Scanner, AST-Bounded Taint Analyzer & Dual-Oracle Remediation Engine.**  
> Find verified vulnerabilities, eliminate false positives through multi-agent consensus, and apply Dual-Oracle verified code patches in seconds.

---

## ⚡ Key Capabilities

* 🔒 **Sovereign Local Mode (BYOM)**: Run 100% locally using your own LLM provider keys (Anthropic Claude, OpenAI, Google Gemini, GCP Vertex AI, Azure OpenAI, or local Ollama/vLLM). **Zero source code leaves your machine.**
* 🤖 **Multi-Agent SAIF Pipeline**: Five specialized agents (Researcher, Prosecutor, Defender, Critic, and Dual-Oracle Judge) collaboratively audit code, discover taint paths, and synthesize dynamic PoC exploits to mathematically verify reachability.
* 🧪 **Dual-Oracle Verified Patches**: Synthesizes surgical code fixes and validates them against both static AST syntax checks and dynamic exploit neutralizers before presenting them to you.
* 🛠️ **Interactive Patch Manager**: Review colorized unified diffs and apply fixes directly to your repository with a single command (`cyfendo patch <id> --apply`).
* 🎯 **Fine-Grained Deduplication & Benchmarking**: Supports `root_cause`, `file` (per-file isolation), and `none` deduplication scopes, plus a dedicated `--benchmark-mode` for OWASP Benchmark / Juliet suites.
* 🚦 **CI/CD Quality Gates**: Native OASIS SARIF 2.1.0 export and configurable severity threshold gates (`--fail-on=high`) for GitHub Actions, GitLab CI, and CircleCI.

---

## 🚀 Installation

### Option A: Install via pip (Recommended)
```bash
pip install --upgrade cyfendo
```

Or isolate dependencies with `pipx`:
```bash
pipx install cyfendo
```

### Option B: Standalone Native Binary (Zero Python Required)
For air-gapped servers or environments without a Python runtime:
```bash
curl -sSL https://cyfendo.com/install.sh | bash
```
*(Or download the binary directly from [https://cyfendo.com/downloads/cyfendo](https://cyfendo.com/downloads/cyfendo) and verify SHA-256 checksums at [checksums.txt](https://cyfendo.com/downloads/checksums.txt)).*

---

## 🔒 1. Sovereign BYOM Mode (Zero Source Code Egress)

Cyfendo Sovereign BYOM is engineered for defense, healthcare, fintech, and enterprise teams with strict zero-trust data custody requirements:
* **100% Local Pipeline Execution**: AST parsing, cross-file taint analysis, call graphs, exploit verification, and patch synthesis execute directly on your local workstation.
* **Direct LLM Connection**: Your machine communicates directly with your chosen provider. Cyfendo servers never proxy your code or model prompts.
* **Local Storage in `.cyfendo/`**: All findings, exploit traces, Markdown reports, SARIF files, and individual `.patch` diffs are stored exclusively in your local workspace.

### Step-by-Step Setup:

#### Step 1: Authenticate Workspace (Optional for Local BYOM)
Generate an API Key from **User Menu → Developer & CLI Access** on [https://cyfendo.com](https://cyfendo.com) to verify plan entitlements:
```bash
cyfendo login --key cy_live_xxxxxxxxxxxxxxxxxxxxxxxx
cyfendo status
```

#### Step 2: Configure Provider Credentials
Export your provider API key or credentials as environment variables:

```bash
# OpenAI (GPT-4o, GPT-4.5, O3-Mini, O1):
export OPENAI_API_KEY="sk-proj-xxxxxxxxxxxxxxxxxxxxxxxx"

# Anthropic Claude (Claude 3.7 Sonnet, Claude 3.5 Sonnet):
export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxxxxxxxxxxxxx"

# Google Gemini Developer API:
export GEMINI_API_KEY="AIzaSyxxxxxxxxxxxxxxxxxxxx"

# Google Cloud Vertex AI (with enterprise ADC):
gcloud auth application-default login
export GCP_PROJECT="my-enterprise-gcp-project"
export VERTEX_AI_LOCATION="us-central1"

# Microsoft Azure OpenAI Service:
export AZURE_OPENAI_ENDPOINT="https://my-resource.openai.azure.com/"
export AZURE_OPENAI_KEY="xxxxxxxxxxxxxxxxxxxxxxxx"
export AZURE_OPENAI_DEPLOYMENT="my-gpt4o-deployment"
```

#### Step 3: Set Persistent Defaults (Optional)
Save your preferred provider and model defaults in `~/.cyfendo/config.json` so you don't need to pass flags each time:
```bash
cyfendo config --set-provider anthropic
cyfendo config --set-model claude-3-7-sonnet-latest
cyfendo config --set-thinking high
cyfendo config --show
```

#### Step 4: Execute the Sovereign Local Scan
Run `cyfendo scan --local .` (or `cyfendo scan --byom .`) on your target directory:

```bash
# 1. Local scan with OpenAI GPT-4o and patch generation:
cyfendo scan --local \
    --provider openai \
    --model gpt-4o \
    --generate-patch \
    .

# 2. Local scan with Anthropic Claude 3.7 Sonnet and extended reasoning:
cyfendo scan --local \
    --provider anthropic \
    --model claude-3-7-sonnet-latest \
    --thinking high \
    --generate-patch \
    .

# 3. Local scan with Google Gemini 3.7:
cyfendo scan --local \
    --provider gemini \
    --model gemini-3.7-flash \
    --generate-patch \
    .

# 4. Local scan with GCP Vertex AI:
cyfendo scan --local \
    --provider vertex \
    --model gemini-3.7-flash \
    --generate-patch \
    .

# 5. Local scan with Microsoft Azure OpenAI:
cyfendo scan --local \
    --provider azure \
    --generate-patch \
    .

# 6. Custom OpenAI-compatible proxy gateway (corporate LiteLLM proxy):
cyfendo scan --local \
    --provider openai \
    --endpoint "https://ai-proxy.corp.internal/v1" \
    --model gpt-4o \
    .

# 7. 100% Air-Gapped Local Models via Ollama (Zero Internet Packets):
# Pull model: ollama pull deepseek-r1:32b
cyfendo scan --local \
    --provider ollama \
    --model deepseek-r1:32b \
    --generate-patch \
    .

# 8. Local scan with self-hosted vLLM cluster:
cyfendo scan --local \
    --provider ollama \
    --endpoint "http://vllm-cluster.internal:8000/v1" \
    --model deepseek-ai/DeepSeek-R1 \
    .
```

---

## ☁️ 2. Managed Cloud Platform Scanning

For centralized team reporting, automated periodic Git schedules, and cloud dashboard triage:

```bash
# 1. Authenticate with your Cyfendo API Key
cyfendo login --key cy_live_xxxxxxxxxxxxxxxx

# 2. Run a vulnerability scan in current directory
cyfendo scan .

# 3. Associate scan with an existing protected project
cyfendo scan /path/to/source --project "payment-gateway"

# 4. View account and workspace status
cyfendo whoami
cyfendo status
cyfendo projects
```

---

## ⚙️ 3. Scan Settings & Advanced Options

### A. Deduplication Scopes (`--dedup-scope`)
Controls how raw taint traces and candidate findings across call graphs and AST scopes are clustered:
* **`root_cause` (Default)**: Universal multi-factor AST clustering across functions and routes. Consolidates redundant alerts into single root-cause findings for developer triage.
* **`file` (Per-File Isolation)**: Prevents findings in separate files from merging. Crucial for synthetic test suites and granular file-by-file audits.
* **`none` (Raw Traces)**: Disables deduplication clustering entirely. Outputs every verified candidate finding trace directly.

```bash
# Run with per-file deduplication and full AI patch generation
cyfendo scan . --dedup-scope=file --generate-patch

# Run raw audit without any deduplication
cyfendo scan . --dedup-scope=none
```

### B. Benchmark Evaluation Mode (`--benchmark-mode`)
Designed for automated evaluation benchmarks (such as OWASP Benchmark, Juliet, and custom synthetic suites). Enforces **Per-File Isolation** (`--dedup-scope=file`) and disables initial patch generation for maximum evaluation throughput and exact groundtruth comparison:
```bash
cyfendo scan . --benchmark-mode
```

### C. Developer Steering Directives (`--directive`)
Guide the multi-agent researcher to focus its audit on specific architecture layers or threat vectors:
```bash
cyfendo scan --local \
    --provider openai \
    --model gpt-4o \
    --directive "Focus audit on authentication bypass, BOLA, and SSRF in payment endpoints" \
    .
```

### D. Fresh Scan Without Checkpoint Cache (`--clean`)
Clears all cached analysis stage checkpoints and forces a fresh scan from scratch:
```bash
cyfendo scan --local --clean .
```

---

## 🩹 4. Inspecting & Applying Remediation Patches

All generated artifacts are saved to `.cyfendo/` in your project root. Cyfendo generates verified, production-ready unified `.patch` files:

```bash
# 1. List and export individual .patch files into .cyfendo/patches/
cyfendo patches

# 2. Inspect a colorized diff preview for a specific finding
cyfendo patch fnd_91a4 --show

# 3. Apply patch directly to local source code via 3-way git apply
cyfendo patch fnd_91a4 --apply

# 4. Or apply manually with standard git tooling
git apply .cyfendo/patches/01_sql_injection.patch

# 5. Export an aggregated unified patch bundle during scan
cyfendo scan . --generate-patch --patch-bundle fixes.patch
git apply fixes.patch

# 6. Read full Markdown audit report
cat .cyfendo/report.md
```

---

## 🚦 5. CI/CD Quality Gates & Automation

Enforce shift-left security on every pull request. Automatically block PR merges with failing quality gates, upload standard SARIF reports, or execute 100% Sovereign BYOM scans with zero code egress.

### CLI Gate Flags:
* `--fail-on=<critical|high|medium|low>`: Exits with code `1` if findings at or above the threshold exist.
* `--sarif=<path>`: Exports findings in OASIS SARIF 2.1.0 format for GitHub Code Scanning / GitLab.
* `--no-interactive`: Disables animated spinners and progress bars for clean CI log output.

---

### GitHub Actions Workflow (Sovereign BYOM — Zero Source Code Egress)
```yaml
name: Cyfendo Sovereign Security Audit

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  cyfendo-security-audit:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

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

      - name: Install Cyfendo CLI
        run: pip install --upgrade cyfendo

      - name: Execute Sovereign BYOM Security Scan
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          cyfendo scan . \
            --local \
            --provider anthropic \
            --model claude-3-7-sonnet-latest \
            --thinking high \
            --sarif results.sarif \
            --fail-on high \
            --no-interactive

      - name: Upload SARIF to GitHub Code Scanning
        uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: results.sarif
```

---

### GitHub Actions Workflow (Managed Cloud)
```yaml
name: Cyfendo Cloud Audit

on:
  pull_request:
    branches: [main]

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

      - name: Install Cyfendo CLI
        run: pip install --upgrade cyfendo

      - name: Run Cloud Security Gate
        env:
          CYFENDO_API_KEY: ${{ secrets.CYFENDO_API_KEY }}
        run: |
          cyfendo scan . \
            --project "my-repo" \
            --fail-on high \
            --sarif results.sarif \
            --no-interactive

      - name: Upload SARIF Report
        uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: results.sarif
```

---

### GitLab CI Workflow (`.gitlab-ci.yml`)
```yaml
cyfendo_security_scan:
  stage: test
  image: python:3.12-slim
  script:
    - pip install --upgrade cyfendo
    - cyfendo scan . --local --provider openai --model gpt-4o --sarif gl-sast-report.sarif --fail-on high --no-interactive
  artifacts:
    reports:
      sast: gl-sast-report.sarif
    when: always
```

---

## 📖 Complete CLI Command Reference

| Command / Flag | Description | Example |
| :--- | :--- | :--- |
| `cyfendo login` | Authenticates CLI and stores credentials in `~/.cyfendo/config.json`. | `cyfendo login --key cy_live_...` |
| `cyfendo whoami` | Displays active user account, role, organization, and quota usage. | `cyfendo whoami` |
| `cyfendo status` | Checks Protected LOC balance, plan limit, and grace period status. | `cyfendo status` |
| `cyfendo projects` | Lists active protected projects in your workspace with LOC counts. | `cyfendo projects` |
| `cyfendo scan <path>` | Packages directory, uploads to Cyfendo cloud sandbox, and streams live audit telemetry. | `cyfendo scan .` |
| `cyfendo scan --local <path>` | **Sovereign BYOM Mode:** 100% local execution with zero source code egress using your own LLM keys. | `cyfendo scan --local .` |
| `--provider <name>` | Specifies AI provider for local BYOM scan: `openai`, `anthropic`, `gemini`, `vertex`, `azure`, or `ollama`. | `--provider openai` |
| `--model <name>` | Target LLM model (`gpt-4o`, `claude-3-7-sonnet-latest`, `gemini-3.7-flash`, `deepseek-r1:32b`). | `--model claude-3-7-sonnet-latest` |
| `--llm-key <key>` | Direct API key for chosen provider (or via `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.). | `--llm-key sk-ant-...` |
| `--endpoint <url>` | Custom OpenAI-compatible base URL for corporate proxies, vLLM, or self-hosted Ollama. | `--endpoint http://localhost:11434/v1` |
| `--thinking <level>` | Sets reasoning effort level for thinking models (`off`, `none`, `low`, `medium`, `high`). | `--thinking high` |
| `--directive <text>` | Developer steering directive to focus vulnerability research on specific areas. | `--directive "Focus on BOLA & auth"` |
| `cyfendo config` | Inspects or configures persistent CLI defaults (`--set-provider`, `--set-model`, `--set-thinking`, `--set-llm-key`, `--set-endpoint`, `--show`). | `cyfendo config --set-provider anthropic` |
| `--project, -p` | Binds scan run to an existing Protected Project name or ID. | `--project "backend-api"` |
| `--dedup-scope <scope>` | Sets vulnerability deduplication scope: `root_cause` (default), `file` (per-file isolation), or `none` (raw traces). | `--dedup-scope=file` |
| `--benchmark-mode` | Runs in benchmark evaluation mode (overrides `--dedup-scope=file` and disables patch generation). | `--benchmark-mode` |
| `--generate-patch` | Synthesizes and sandbox-verifies AI remediation patches during scan. | `--generate-patch` |
| `--no-patch` | Explicitly skips remediation patch generation (default fast PoC mode). | `--no-patch` |
| `--patch-bundle <path>` | Exports aggregated unified remediation diff bundle file. | `--patch-bundle fixes.patch` |
| `--fail-on <level>` | Exits with code 1 if findings at or above threshold exist (`critical`, `high`, `medium`, `low`). | `--fail-on=high` |
| `--output, -o <path>` | Custom destination path for export JSON report (defaults to `.cyfendo/scan-results.json`). | `--output results.json` |
| `--sarif <path>` | Exports findings in OASIS SARIF 2.1.0 JSON format for GitHub / IDE integration. | `--sarif=results.sarif` |
| `--clean` | Clears all cached analysis stage checkpoints and forces a fresh scan from scratch. | `--clean` |
| `--no-interactive` | Disables animated spinners and progress bars for clean CI/CD log output. | `--no-interactive` |
| `-v, --verbose` | Enables verbose diagnostic traces and model communication logs. | `cyfendo scan --local -v .` |
| `cyfendo patches [id]` | Lists and exports all individual vulnerability `.patch` diffs. | `cyfendo patches` |
| `cyfendo patch <target>` | Inspects (`--show`) or applies (`--apply`) a vulnerability patch to local files. | `cyfendo patch fnd_91a4 --show` |
| `cyfendo logout` | Clears stored credentials from `~/.cyfendo/config.json`. | `cyfendo logout` |

---

## 📄 License & Links

* **License**: MIT
* **Homepage**: [https://cyfendo.com](https://cyfendo.com)
* **Documentation**: [https://cyfendo.com/docs](https://cyfendo.com/docs)
* **Issues & Feedback**: [contact@cyfendo.com](mailto:contact@cyfendo.com)
