Skip to main content
Thank you for your interest in contributing to Esprit! This guide will help you understand our contribution process and best practices.

​
Getting Started

1

Set up your environment

Follow the development setup guide to configure your local environment:
git clone https://github.com/esprit-cli/Esprit.git
cd Esprit
make setup-dev
2

Choose what to contribute

You can contribute in several ways:
  • Skills: Add security knowledge packages
  • Code: Fix bugs or implement features
  • Documentation: Improve docs and examples
  • Testing: Add test coverage
  • Bug reports: Report issues with details
3

Create an issue (for code changes)

Before starting work on code changes:
  1. Check existing issues
  2. Create a new issue describing the problem or feature
  3. Wait for maintainer feedback before investing significant time

​
Contributing Skills

Skills are specialized knowledge packages that enhance agent capabilities. They’re the easiest way to contribute!

​
Skill Categories

Skills are organized by category:
  • /vulnerabilities - Security vulnerability knowledge (SQL injection, XSS, etc.)
  • /frameworks - Framework-specific testing (Django, Rails, Next.js, etc.)
  • /technologies - Technology platforms (Firebase, Supabase, etc.)
  • /protocols - Protocol testing (GraphQL, OAuth, WebSocket, etc.)
  • /reconnaissance - Information gathering techniques
  • /cloud - Cloud platform security (AWS, GCP, Azure, etc.)
  • /scan_modes - Scan mode definitions (quick, standard, deep)

​
Creating a Skill

1

Choose the right category

Pick the most appropriate category for your skill:
esprit/skills/vulnerabilities/  # For vulnerability types
esprit/skills/frameworks/       # For framework-specific knowledge
esprit/skills/technologies/     # For specific technologies
2

Create a Markdown file

Create a .md file with your skill content:
# Example: Adding GraphQL vulnerability knowledge
touch esprit/skills/protocols/graphql.md
3

Write comprehensive content

Include these sections in your skill:
# GraphQL Security Testing

## Overview
Brief description of the vulnerability or technique.

## Detection Methods
How to identify this vulnerability or technology.

## Exploitation Examples
Practical examples with working payloads.

## Validation
How to confirm findings and avoid false positives.

## Remediation
How to fix or mitigate the issue.
4

Include practical examples

Provide working examples with code snippets:
query IntrospectionQuery {
  __schema {
    types {
      name
    }
  }
}
5

Submit your skill

Create a pull request with:
  • Clear title describing the skill
  • Description of what knowledge it adds
  • Examples of when it would be useful

​
Skill Guidelines

Focus on practical, actionable information:Good: “Send a GraphQL introspection query to enumerate all types and fields”Bad: “GraphQL APIs might have security issues”
Provide actual payloads and commands that work:
# Test for SQL injection
curl "https://example.com/api/users?id=1' OR '1'='1"
Show how to verify findings:
## Validation
- Check if the response includes unauthorized data
- Verify the query executed successfully
- Confirm the payload wasn't sanitized
Each skill should cover one specific topic:
  • One vulnerability type per file
  • One framework per file
  • One protocol per file

​
Contributing Code

​
Pull Request Process

1

Fork and create a branch

# Fork the repository on GitHub
git clone https://github.com/YOUR_USERNAME/Esprit.git
cd Esprit

# Create a feature branch
git checkout -b feature/your-feature-name
2

Make your changes

Follow the code style guidelines and write tests for new features:
# Make changes
vim esprit/agents/new_feature.py

# Add tests
vim tests/agents/test_new_feature.py
3

Run quality checks

Ensure all checks pass before committing:
make check-all
This runs:
  • Code formatting (Ruff)
  • Linting (Ruff + Pylint)
  • Type checking (mypy + pyright)
  • Security checks (Bandit)
4

Run tests

Verify your changes don’t break existing functionality:
make test-cov
Aim for >80% code coverage for new code.
5

Commit your changes

Write clear, descriptive commit messages:
git add .
git commit -m "Add GraphQL introspection detection to scan agent"
6

Push and create PR

git push origin feature/your-feature-name
Then create a Pull Request on GitHub with:
  • Clear description of changes
  • Link to related issue
  • Screenshots/examples if applicable

​
PR Guidelines

Clear Description

Explain what changed and why

Small & Focused

One feature or fix per PR

Include Examples

Show before/after behavior

Update Docs

Document new features

​
Code Style

Esprit follows strict code quality standards:

​
Style Requirements

  • PEP 8 compliance with 100-character line limit
  • Type hints for all function parameters and return values
  • Docstrings for all public methods and classes
  • Meaningful names - No single-letter variables (except loop counters)
  • Small functions - Keep functions focused and under 50 lines

​
Example Code

from typing import Optional

class ScanAgent:
    """Agent responsible for coordinating security scans.
    
    Attributes:
        target: The URL or path to scan
        mode: Scan mode (quick, standard, deep)
        timeout: Maximum scan duration in seconds
    """
    
    def __init__(self, target: str, mode: str = "standard", timeout: int = 3600) -> None:
        """Initialize the scan agent.
        
        Args:
            target: URL or file path to scan
            mode: Scan intensity level
            timeout: Maximum scan time in seconds
        """
        self.target = target
        self.mode = mode
        self.timeout = timeout
    
    def execute_scan(self, depth: Optional[int] = None) -> dict[str, any]:
        """Execute the security scan.
        
        Args:
            depth: Maximum crawl depth (None for unlimited)
            
        Returns:
            Dictionary containing scan results and findings
            
        Raises:
            ValueError: If target is invalid
            TimeoutError: If scan exceeds timeout
        """
        # Implementation here
        pass

​
Type Checking

Esprit uses strict type checking with both mypy and pyright: 
# Good - Fully typed
def process_results(findings: list[dict[str, any]], severity: str) -> int:
    """Process scan findings and return count."""
    return len([f for f in findings if f["severity"] == severity])

# Bad - Missing types
def process_results(findings, severity):
    return len([f for f in findings if f["severity"] == severity])

​
Code Formatting

Ruff handles formatting automatically: 
# Format all code
make format

# Or manually
poetry run ruff format .
Configuration (from pyproject.toml):
  • Line length: 100 characters
  • Quote style: Double quotes
  • Target: Python 3.12+

​
Testing Requirements

​
Test Coverage

  • New features: Must include tests
  • Bug fixes: Add regression tests
  • Coverage target: >80% for new code
  • All tests must pass: No skipped tests in PRs

​
Writing Tests

See the Testing Guide for detailed examples. Quick example: 
import pytest
from esprit.agents.scan_agent import ScanAgent

def test_scan_agent_validates_url():
    """Test that scan agent rejects invalid URLs."""
    with pytest.raises(ValueError, match="Invalid URL"):
        ScanAgent(target="not-a-url")

@pytest.mark.asyncio
async def test_scan_agent_executes_successfully():
    """Test successful scan execution."""
    agent = ScanAgent(target="https://example.com", mode="quick")
    result = await agent.execute_scan()
    assert result["status"] == "completed"
    assert "findings" in result

​
Reporting Issues

When reporting bugs, include:
1

Environment details

# Include this information
- Python version: 3.12.1
- Esprit version: 0.7.20
- Operating System: Ubuntu 22.04
- Docker version: 24.0.5
2

LLM configuration

- Provider: Anthropic
- Model: claude-sonnet-4-5
- Using Docker: Yes
3

Full error traceback

# Copy the complete error output
Traceback (most recent call last):
  File "...", line X, in <module>
    ...
4

Steps to reproduce

1. Run: esprit scan https://example.com
2. Wait for initialization
3. Error occurs at: ...
5

Expected vs actual behavior

  • Expected: Scan should complete successfully
  • Actual: Scan fails with ConnectionError

​
Feature Requests

We welcome feature ideas! When requesting features:
  1. Check existing issues - Your idea might already be planned
  2. Describe the use case - Explain the problem you’re solving
  3. Explain the benefit - How would this help users?
  4. Consider implementation - Any thoughts on how it could work?
  5. Be open to discussion - Maintainers may suggest alternatives

​
Feature Request Template

## Problem Statement
Describe the problem or limitation you're facing.

## Proposed Solution
Your idea for solving the problem.

## Use Case
Real-world scenario where this would be useful.

## Alternatives Considered
Other solutions you've thought about.

## Additional Context
Any other relevant information.

​
Community

Join the Esprit community:

​
Recognition

We value all contributions! Contributors will be:
  • Listed in release notes
  • Thanked in our Discord community
  • Recognized in the project’s contributors list
  • Invited to join contributor channels

​
Development Workflow Summary

Quick reference for the complete development cycle: 
# 1. Set up environment
git clone https://github.com/esprit-cli/Esprit.git
cd Esprit
make setup-dev

# 2. Create feature branch
git checkout -b feature/my-feature

# 3. Make changes and test
vim esprit/...
make check-all
make test-cov

# 4. Commit and push
git add .
git commit -m "Add feature: ..."
git push origin feature/my-feature

# 5. Create PR on GitHub

​
Questions?

Need help? We’re here for you:
Thank you for contributing to Esprit! Every contribution, no matter how small, helps make security testing more accessible and effective.

Build docs developers (and LLMs) love

Get started for freeTalk to us