| # 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: |
| ```bash |
| pip install -e ".[dev]" |
| pytest tests/ -v |
| python -m benchmarks.benchmark |
| ``` |
| 5. Ensure code style: |
| ```bash |
| 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 |
|
|
| ```bash |
| # 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. |
|
|
