CONTRIBUTING.md

Contributing to IntelliScan

Thank you for your interest in contributing to IntelliScan! This document outlines the process and guidelines for contributing.

Code of Conduct

• Be respectful and constructive in all interactions
• Focus on what is best for the community and the project
• Show empathy towards other community members

How to Contribute

Reporting Bugs

Before submitting a bug report:

1. Search existing issues to avoid duplicates
2. Verify reproduction on the latest version
3. Test against DVWA in Docker to isolate from environment issues

When opening a bug report, include:

• Python version and OS
• Full stack trace if applicable
• Minimal reproduction steps
• Expected vs actual behavior

Suggesting Features

Feature requests are welcome! Please:

1. Check the Roadmap first
2. Open an issue with the enhancement label
3. Describe the use case and motivation
4. If possible, sketch the API or behavior

Submitting Pull Requests

1. Fork the repo and create a feature branch:

   git checkout -b feature/my-feature
   

2. Set up the dev environment:

   pip install -r requirements-dev.txt
   pre-commit install
   

3. Make your changes with:

   • Clear, focused commits
   • Type hints where applicable
   • Docstrings for public functions/classes
   • Tests for new functionality

4. Run the test suite:

   pytest tests/ --cov=intelliscan
   black intelliscan/
   ruff check intelliscan/
   

5. Submit the PR with:

   • A clear title and description
   • Reference to any related issue
   • Screenshots/output examples if UI-related

Coding Standards

Python Style

• Formatter: Black (default settings)
• Linter: Ruff (config in pyproject.toml)
• Type hints: required for public APIs, recommended elsewhere
• Docstrings: required for modules, classes, and public functions (numpy style)
• Line length: 100 characters

Module Structure

Every module should:

1. Start with a docstring describing its purpose
2. Use absolute imports
3. Define a clear public API via __all__ if non-trivial
4. Include a CLI entry point (if __name__ == "__main__":) if usable standalone

Tests

• Place tests in tests/test_<module>.py
• Use pytest fixtures from conftest.py
• Aim for >80% coverage on new code
• Mock network calls in unit tests; integration tests can use DVWA

Adding a New Vulnerability Type

To add support for a new vulnerability class (e.g., CSRF, SSRF):

1. Add payloads in payloads/<vuln_type>.txt
2. Update config.py:
   • Add to PAYLOAD_FILES
   • Add to DVWA_FORMS (target endpoint)
   • Add to SEVERITY
   • Add detection signatures if applicable
3. Update analyzer.py:
   • Add a _detect_<vuln_type> static method
   • Wire it into _classify
4. Add tests in tests/test_analyzer.py
5. Update README comparison tables and documentation

Releasing

(For maintainers)

1. Update version in intelliscan/__init__.py and setup.py
2. Update CHANGELOG.md
3. Tag the release: git tag v1.x.y && git push --tags
4. GitHub Actions will publish the Docker image

Questions?

Open a GitHub Discussion or reach out via the contact info in the README.