FlowSec

A Python command-line security tool that scans CI/CD pipeline configurations for attack vectors across GitHub Actions, GitLab CI, and Azure DevOps. Every finding maps to a MITRE ATT&CK technique and an OWASP CICD Top 10 category.

The pipeline is the attack surface. FlowSec treats it that way.

Install

Homebrew (macOS):

brew install VanshBhardwaj1945/flowsec/flowsec

PyPI:

pip install flowsec                # local file/directory scanning
pip install "flowsec[remote]"      # + remote repo scanning
pip install "flowsec[ai]"          # + AI attack narratives

Quick Start

# Scan your repo checkout (finds .github/workflows/ automatically)
flowsec scan --github --dir .

# Scan a remote GitHub repo (public repos work without a token)
flowsec scan --github --repo owner/repo

# Scan a local GitHub Actions workflow file
flowsec scan --github --file .github/workflows/ci.yml

# Scan a GitLab CI file
flowsec scan --gitlab --file .gitlab-ci.yml

# Scan an Azure DevOps pipeline file
flowsec scan --azure --file azure-pipelines.yml

# JSON to stdout — pipe it anywhere
flowsec scan --github --dir . --format json

# SARIF for GitHub code scanning
flowsec scan --github --dir . --format sarif --output results.sarif

# Generate an HTML report
flowsec scan --github --dir . --format html --output report.html

# Generate AI attack narratives (requires ANTHROPIC_API_KEY)
flowsec scan --github --dir . --ai

# Fail pipeline if findings at or above threshold
flowsec scan --github --dir . --fail-on critical

# Ignore specific rules
flowsec scan --github --dir . --ignore FS006 --ignore FS011

Exit codes: 0 clean scan, 1 when --fail-on triggers, 2 for usage or scan errors.

Platforms and Tokens

Set tokens in a .env file in your working directory or as environment variables. FlowSec loads .env automatically. Remote scanning needs pip install "flowsec[remote]".

38 Security Rules

Risk Score

Every scan produces a 0-100 risk score using severity-weighted diminishing returns and exponential normalization. A single critical finding scores ~28. A heavily vulnerable pipeline scores ~90-97. The score cannot exceed 100.

Rule Suppression

# CLI flag
flowsec scan --github --repo owner/repo --ignore FS006 --ignore FS011

# .flowsec.yml in your repo root

ignore:
  - rule_id: FS006
    reason: "We use external timeout management"
  - rule_id: FS002
    file: "legacy/*.yml"
    reason: "Legacy pipelines are being retired, not fixed"

The optional file field limits the ignore to files matching a glob.

Use as a Pipeline Gate

name: FlowSec Security Scan
on: [push, pull_request]
jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install flowsec
      - run: flowsec scan --github --dir . --fail-on critical

Or upload SARIF to GitHub's Security tab:

      - run: flowsec scan --github --dir . --format sarif --output flowsec.sarif
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: flowsec.sarif

Security

FlowSec is built to the same standard it enforces:

• All GitHub Actions pinned to commit SHAs with least-privilege permissions
• PyPI publishing via OIDC trusted publishing — no long-lived tokens
• Own CI runs gitleaks, bandit, pip-audit, and FlowSec self-scan on every push
• Branch protection on main — force push blocked, 4 required status checks
• YAML parsed with a SafeLoader subclass — no code execution risk
• HTML reports use Jinja2 autoescape — XSS from finding content prevented

Report vulnerabilities via GitHub Security Advisories or email Scorpio.vansh@gmail.com.

License

MIT — see LICENSE on GitHub.

Source: https://github.com/VanshBhardwaj1945/FlowSec