CONTRIBUTING.md

Contributing to Shield Agents

First off, thank you for considering contributing to Shield Agents! It's people like you that make this tool better for everyone.

How to Contribute

Reporting Bugs

Before creating bug reports, please check the existing issues. When you create a bug report, include as many details as possible:

• OS and Python version
• Shield Agents version (shield-agents version)
• Steps to reproduce
• Expected vs actual behavior
• Scan output or error messages

Suggesting Enhancements

Enhancement suggestions are tracked as GitHub issues. Include:

• Use case - why is this needed?
• Expected behavior - what should it do?
• Current workaround - is there an alternative?

Pull Requests

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run the test suite:

   pip install -e ".[dev]"
   pytest tests/ -v
   python -m benchmarks.benchmark
   

5. Ensure code style:

   ruff check shield_agents/
   black --check shield_agents/
   

6. Commit with a clear message (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

Adding New SAST Rules

1. Add the rule to shield_agents/scanners/sast.py in the SAST_RULES list
2. Add a test case in tests/test_sast.py
3. Add a benchmark case in benchmarks/benchmark.py (optional but recommended)
4. Update the README with the new rule

Adding New Secret Patterns

1. Add the pattern to shield_agents/scanners/secrets.py in SECRET_PATTERNS
2. Add a test case in tests/test_secrets.py
3. Consider entropy filtering to reduce false positives

Adding New Agents

1. Create a new file in shield_agents/agents/
2. Extend BaseAgent and implement analyze() and get_system_prompt()
3. Add agent-specific patterns to the MockProvider in llm.py
4. Register in shield_agents/agents/__init__.py
5. Add configuration in config.py
6. Wire into the orchestrator in orchestrator.py
7. Add tests and update README

Development Setup

# Clone the repository
git clone https://github.com/shield-agents/shield-agents.git
cd shield-agents

# Create a virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
# or venv\Scripts\activate on Windows

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Run benchmarks
python -m benchmarks.benchmark --verbose

# Run linter
ruff check shield_agents/

Code Style

• Follow PEP 8
• Use type hints
• Maximum line length: 100 characters
• Use ruff for linting
• Use black for formatting

License

By contributing, you agree that your contributions will be licensed under the MIT License.