Skip to content

README.md

Latest commit

 

History

History
156 lines (116 loc) · 5.48 KB

README.md

File metadata and controls

156 lines (116 loc) · 5.48 KB

SecNode API

Autonomous, AI-augmented API penetration testing framework.


GitHub Stars License PyPI Version

SecNode Overview

SecNode API is an autonomous AI agentic penetration testing framework in Python. It ingests Swagger/OpenAPI schemas, reasons over the business context with an LLM, generates highly contextual and adversarial test cases, executes them concurrently, and automatically produces audit-grade vulnerability reports.

Built for security engineers and developers who need robust Dynamic Application Security Testing (DAST) without the noise of false positives.

Key Capabilities:

  • Zero False Positives Workflow via strict validation and deterministic re-execution.
  • Deep Business Logic Analysis tailored to your API's specific domain and trust boundaries.
  • OWASP API Security Top 10 (2023) Coverage, perfectly mapped to BOLA, BOPLA, BFLA, and more.
  • Asynchronous Execution Engine pushing high-volume, concurrent attack probes.
  • Provider-Agnostic LLM Integration powered by LiteLLM (OpenAI, Anthropic, Gemini, local models).
  • Auto-Generated Reporting producing actionable Markdown and machine-readable JSON outputs.

Use Cases

  • Application Security Testing - Detect and validate critical API vulnerabilities automatically in CI/CD.
  • Rapid Penetration Testing - Execute an entire API pentest in minutes rather than weeks.
  • Bug Bounty Automation - Automatically discover business logic flows and exploit chains.
  • Continuous Compliance - Maintain a continuous security posture aligned with OWASP Top 10.

🚀 Quick Start

Prerequisites:

  • Python 3.9+
  • An LLM API key (e.g. OpenAI)

Installation & First Scan

# Clone the repository
git clone https://github.com/secnode/secnodeapi.git
cd secnodeapi

# Setup virtual environment and dependencies
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Configure your AI provider
export SECNODE_LLM="openai/gpt-4o"
export OPENAI_API_KEY="your-api-key"

# Run your first security assessment
python3 secnodeapi.py --target https://api.your-app.com/swagger.yaml

Note

Scan reports and findings are saved to timestamped directories in results/<target_domain>_<timestamp>/

✨ Features

Agentic Security Testing Engine

SecNode operates via a strict agentic pipeline:

  • Schema Fetcher - Downloads, parses, and resolves complex OpenAPI definitions.
  • Cognitive AI Engine - Reads the API structure, deduces trust boundaries, and flags high-risk flows.
  • Exploit Generator - Specifically generates deep attack vectors like UUID swapping or parameter mass assignment.
  • Parallel Test Executor - Fires async requests rapidly while respecting internal rate limits.
  • False-Positive Eliminator - Uses validate_and_retest loop with deterministic re-execution and a "Chain-of-Thought" elite app-sec triage prompt.

Comprehensive Vulnerability Detection

SecNode rigorously hunts for:

  • Access Control - BOLA (IDOR) and BFLA (Privilege Escalation).
  • Mass Assignment - BOPLA and sensitive field overriding.
  • Resource Constraints - Rate Limit bypasses, infinite pagination.
  • Business Logic - State machine skipping, negative price manipulation, validation bypass.

Usage Examples

Basic Usage

# Scan an API using a remote Swagger JSON
python3 secnodeapi.py --target http://vulnapi.your-app.com/swagger.json

# Scan an API using a local OpenAPI YAML file
python3 secnodeapi.py --target ./docs/openapi.yaml

Advanced Testing Scenarios

# Authenticated Testing (using inline Bearer token)
python3 secnodeapi.py --target https://api.your-app.com/docs \
  --auth-header "Authorization: Bearer my-jwt-token"

# Authenticated Testing (using a JSON auth file)
python3 secnodeapi.py --target https://api.your-app.com/docs \
  --auth-file ./config/auth.json

# Proxy Traffic (e.g. send traffic through Burp Suite/ZAP for manual review)
python3 secnodeapi.py --target https://api.your-app.com/docs \
  --proxy http://127.0.0.1:8080

# Control Concurrency (Scale execution speed)
python3 secnodeapi.py --target https://api.your-app.com/docs \
  --concurrency 10

CI/CD (GitHub Actions)

SecNode API can be easily integrated into your DevSecOps pipeline to scan staging APIs before deployment.

name: secnode-api-pentest

on:
  pull_request:

jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.10'

      - name: Install SecNode
        run: pip install -r requirements.txt

      - name: Run SecNode Scan
        env:
          SECNODE_LLM: ${{ secrets.SECNODE_LLM }}
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: python3 secnodeapi.py --target https://staging-api.example.com/swagger.json

Configuration

# Default behavior uses GPT-4o
export SECNODE_LLM="openai/gpt-4o"
export OPENAI_API_KEY="sk-..."

# Or use Anthropic
export SECNODE_LLM="anthropic/claude-3-5-sonnet-20241022"
export ANTHROPIC_API_KEY="sk-ant-..."