Contributing

​

Development Setup

​

Prerequisites

• Python 3.12+ - Required for running Strix
• Docker - Must be running for sandbox environments
• Poetry - For dependency management
• Git - For version control

​

Local Development

1. Clone the repository
   git clone https://github.com/usestrix/strix.git
   cd strix
   
2. Install development dependencies
   make setup-dev
   
   # or manually:
   poetry install --with=dev
   poetry run pre-commit install
   
3. Configure your LLM provider
   export STRIX_LLM="openai/gpt-5"
   export LLM_API_KEY="your-api-key"
   
4. Run Strix in development mode
   poetry run strix --target https://example.com
   

​

Contributing Skills

​

Quick Guide

1. Choose the right category - /vulnerabilities, /frameworks, /technologies, etc.
2. Create a .md file with your skill content
3. Include practical examples - Working payloads, commands, or test cases
4. Provide validation methods - How to confirm findings and avoid false positives
5. Submit via PR with clear description

​

Skill Structure

• YAML frontmatter with name and description
• Advanced techniques specific to the domain
• Practical examples with variations
• Validation and confirmation methods
• Context-specific insights and edge cases

​

Contributing Code

​

Pull Request Process

1. Create an issue first - Describe the problem or feature
2. Fork and branch - Work from the main branch
3. Make your changes - Follow existing code style
4. Write/update tests - Ensure coverage for new features
5. Run quality checks - make check-all should pass
6. Submit PR - Link to issue and provide context

​

PR Guidelines

• Clear description - Explain what and why
• Small, focused changes - One feature/fix per PR
• Include examples - Show before/after behavior
• Update documentation - If adding features
• Pass all checks - Tests, linting, type checking

​

Code Style

• Follow PEP 8 with 100-character line limit
• Use type hints for all functions
• Write docstrings for public methods
• Keep functions focused and small
• Use meaningful variable names

​

Quality Checks

# Run all checks
make check-all

# Individual checks
make lint        # Ruff linting
make typecheck   # MyPy type checking
make test        # Run test suite

​

Reporting Issues

• Python version and OS - e.g., Python 3.12 on Ubuntu 22.04
• Strix version - Check with strix --version
• LLMs being used - e.g., OpenAI GPT-5, Claude Sonnet 4.6
• Full error traceback - Copy the complete error message
• Steps to reproduce - Clear, numbered steps
• Expected vs actual behavior - What should happen vs what does happen

​

Example Bug Report

**Environment:**
- OS: macOS 14.2
- Strix: 0.8.2
- Python: 3.12.1
- LLM: openai/gpt-5

**Issue:**
Docker container fails to start with "port already in use" error.

**Steps to Reproduce:**
1. Run `strix --target https://example.com`
2. Cancel scan (Ctrl+C)
3. Run `strix --target https://example.com` again

**Expected:** Scan starts successfully
**Actual:** Error: "port 48081 already in use"

**Error Log:**
[paste full traceback here]

​

Feature Requests

• Check existing issues first - Avoid duplicates
• Describe the use case clearly - What problem does it solve?
• Explain why it would benefit users - Who needs this?
• Consider implementation approach - How might it work?
• Be open to discussion - We may suggest alternatives

​

Code Review Process

1. Automated checks run - CI/CD pipeline validates your code
2. Maintainer review - A team member reviews your changes
3. Feedback incorporated - You make requested changes
4. Approval and merge - Once approved, we merge your PR

​

Community

• Discord - Join our community for real-time chat
• GitHub Issues - Report bugs and request features
• GitHub Discussions - Share ideas and ask questions

​

Recognition

• Listed in release notes
• Thanked in our Discord community
• Added to the contributors list
• Mentioned in relevant documentation

​

Development Tips

​

Running Tests

# Run all tests
poetry run pytest

# Run specific test file
poetry run pytest tests/test_agents.py

# Run with coverage
poetry run pytest --cov=strix --cov-report=html

​

Debugging

# Enable debug logging
export STRIX_LOG_LEVEL=DEBUG

# Keep container running after scan
export STRIX_KEEP_CONTAINER=true

​

Working with Docker

# View running containers
docker ps

# Access container shell
docker exec -it <container-id> /bin/bash

# View container logs
docker logs <container-id>

# Clean up containers
docker container prune

​

License

​

Questions?