Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
142 lines (104 loc) · 4.23 KB

CONTRIBUTING.md

File metadata and controls

142 lines (104 loc) · 4.23 KB

Contributing to SecNode API

Thank you for your interest in contributing to SecNode API! This guide will help you get started with development and contributions to our autonomous, AI-augmented black-box penetration testing framework.

Development Setup

Prerequisites

  • Python 3.10+
  • Git
  • uv (recommended)

Local Development

  1. Clone the repository

    git clone https://github.com/secnode/secnodeapi.git
cd secnodeapi

  2. Set up a virtual environment

    python3 -m venv venv
source venv/bin/activate

  3. Install dependencies

    make install-dev

    Or with uv:

    make install-dev-uv

  4. Configure your LLM provider

    export SECNODE_LLM="openai/gpt-4o"
export OPENAI_API_KEY="your-api-key"

# Or Anthropic
export SECNODE_LLM="anthropic/claude-3-5-sonnet-20241022"
export ANTHROPIC_API_KEY="your-anthropic-key"

# Or Ollama
export SECNODE_LLM="ollama/llama3.1"
export OLLAMA_API_BASE="http://localhost:11434" # optional

# Or Nebius
export SECNODE_LLM="nebius/meta-llama/Meta-Llama-3.1-70B-Instruct"
export NEBIUS_API_KEY="your-nebius-key"

    Provider credentials are model-specific. openai/* requires OPENAI_API_KEY, anthropic/* requires ANTHROPIC_API_KEY, nebius/* requires NEBIUS_API_KEY, and ollama/* can run locally without cloud API keys. See LiteLLM provider docs for other providers.

  5. Run SecNode in development mode

    secnodeapi --target https://api.example.com/swagger.json

Development quality checks

make lint
make test
make build

With uv:

make lint-uv
make test-uv
make build-uv

Enhancing the AI Engine

SecNode relies heavily on its ai/ package (understand, generate, validate) for cognitive test generation and verification.

Quick Guide

  1. Understand Pipeline Flow: Familiarize yourself with how schema_fetcher, ai_engine, and test_executor interact.
  2. Improve System Prompts: If adding support for new vulnerability classes, update the system prompts inside generate_test_cases().
  3. Refine Heuristics: If the engine is flagging false positives, refine the Chain-of-Thought heuristics inside _evaluate_single_result().
  4. Submit via PR with clear descriptions of the accuracy/coverage improvement.

Contributing Code

Pull Request Process

  1. Create an issue first - Describe the problem or feature you want to build.
  2. Fork and branch - Work from the main branch.
  3. Make your changes - Follow existing code style (use structlog for logging, fully type-hint signatures).
  4. Write/update tests - Ensure new parsing or networking logic handles edge cases.
  5. Submit PR - Link to the original issue and provide context.

PR Guidelines

  • Clear description - Explain what changed and why.
  • Small, focused changes - Do not submit massive rewrites; isolate one feature/fix per PR.
  • Include examples - Show before/after behavior (e.g., sample proxy output, generated findings).
  • Update documentation - If adding new CLI features, update README.md.

Code Style

  • Follow PEP 8 with a 100-character line limit.
  • Use Python type hints (typing) for all functions and Pydantic models.
  • Write docstrings for all public methods.
  • Keep functions tightly focused and under 100 lines.
  • Avoid debug print() statements in library code; use structlog (logger.info(), logger.error()).

Reporting Issues

When reporting bugs, please include:

  • Python version and OS
  • LLM Provider and Model being used
  • Target API structure (if possible to share safely)
  • Full error traceback
  • Steps to reproduce
  • Expected vs actual behavior

Feature Requests

We heavily welcome new feature ideas! Please:

  • Check existing issues first.
  • Describe the core use case clearly.
  • Explain why it would benefit security engineers or developers.
  • Consider the technical implementation approach.

Recognition

We value all contributions! Contributors will be:

  • Listed in our release notes
  • Formally recognized in the repository's contributors list

Questions? Create a GitHub Discussion or Issue. We're here to help you hack smarter!