Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
152 lines (107 loc) · 3.15 KB

CONTRIBUTING.md

File metadata and controls

152 lines (107 loc) · 3.15 KB
Raw

Contributing

Thanks for your interest in AutoPentest Lite. This document covers everything you need to get started.

Development setup

Prerequisites

  • Python 3.12+
  • Node.js 18+
  • Ollama with llama3.1 pulled
  • Security tools: nmap gobuster sqlmap whatweb dirb nikto

Clone and install

git clone https://github.com/Giathi-Daniel/AutoPentest-Lite.git
cd AutoPentest-Lite

# Backend
cd backend
pip install -r requirements.txt

# Frontend
cd ../frontend
npm install

Run locally

# Terminal 1 — backend
cd backend && python main.py --serve --debug

# Terminal 2 — frontend
cd frontend && npm run dev

Running tests

# Backend unit tests
cd backend && pytest

# Frontend e2e tests
cd frontend && npm run test:e2e

All tests must pass before opening a pull request. CI runs both suites automatically.

Adding a new tool

  1. Create backend/tools/<toolname>.py following the existing pattern:
from __future__ import annotations
from .executor import run_command
from .targets import to_host_target   # or to_url_target

def run(target: str, goal: str, timeout: int = 120) -> dict[str, object]:
    return run_command(
        tool="mytool",
        args=["mytool", "--flag", to_host_target(target)],
        target=target,
        goal=goal,
        timeout=timeout,
    )
  1. Register it in backend/tools/__init__.py:
from .mytool import run as run_mytool

_TOOLS: dict[str, ToolRunner] = {
    ...
    "mytool": run_mytool,
}

  1. Add tests in backend/tests/ covering at least: success result, tool not found, timeout.

  2. Add the tool name to the relevant section in README.md.

Adding a CTF chain

Edit _CTF_CHAINS in backend/main.py:

_CTF_CHAINS: dict[str, list[str]] = {
    "web":     ["gobuster", "whatweb", "sqlmap"],
    "network": ["nmap", "dirb", "nikto"],
    "custom":  ["mytool", "anothertool"],   # add here
}

Then add the chain to the CHAINS constant in frontend/src/CtfMode.jsx.

Code style

Python

  • Follow PEP 8
  • Use from __future__ import annotations at the top of every module
  • Type-annotate all public functions
  • Run black and isort before committing: 
    pip install black isort
black backend/
isort backend/

JavaScript / React

  • Functional components only
  • Keep components focused — one responsibility per file
  • MUI sx prop for styles, no inline style={{}}
  • No console.log in committed code

Pull request process

  1. Fork the repo and create a branch: git checkout -b feature/my-feature
  2. Make your changes with tests
  3. Run the full test suite locally
  4. Open a PR against main with a clear description of what changed and why
  5. CI must be green before merge

What we're looking for

  • New tool wrappers (e.g. nuclei, ffuf, wpscan)
  • Improved vulnerability detection patterns in backend/tools/analyze.py
  • UI improvements and accessibility fixes
  • Documentation and example improvements
  • Bug fixes with regression tests

Questions

Open a GitHub Discussion or check FAQ.md first.