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](README.md#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:
   ```bash
   git checkout -b feature/my-feature
   ```

2. **Set up the dev environment**:
   ```bash
   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**:
   ```bash
   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](https://github.com/sabkari-mohamed/intelliscan/discussions) or reach out via the contact info in the README.