diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..bdc74c7 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,38 @@ +# EditorConfig helps maintain consistent coding styles across different editors +# https://editorconfig.org + +root = true + +[*] +charset = utf-8 +end_of_line = lf +insert_final_newline = true +trim_trailing_whitespace = true +indent_style = space +indent_size = 4 + +[*.{py}] +indent_size = 4 +max_line_length = 100 + +[*.{yml,yaml}] +indent_size = 2 + +[*.{json}] +indent_size = 2 + +[*.{html,css,js}] +indent_size = 2 + +[*.md] +trim_trailing_whitespace = false +max_line_length = off + +[Makefile] +indent_style = tab + +[docker-compose*.yml] +indent_size = 2 + +[.env*] +insert_final_newline = false diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..71883a7 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,57 @@ +--- +name: Bug Report +about: Create a report to help us improve +title: '[BUG] ' +labels: 'bug' +assignees: '' +--- + +## Bug Description +A clear and concise description of what the bug is. + +## To Reproduce +Steps to reproduce the behavior: +1. Go to '...' +2. Click on '....' +3. Scroll down to '....' +4. See error + +## Expected Behavior +A clear and concise description of what you expected to happen. + +## Actual Behavior +What actually happened instead. + +## Screenshots +If applicable, add screenshots to help explain your problem. + +## Environment +**Desktop/Server:** +- OS: [e.g. Ubuntu 22.04, Windows 11, macOS 13] +- Browser (if UI issue): [e.g. Chrome 120, Firefox 121] +- Python Version: [e.g. 3.10.5] +- Docker Version (if applicable): [e.g. 24.0.7] +- DMARQ Version: [e.g. 0.1.0] + +**Deployment Method:** +- [ ] Docker Compose +- [ ] Manual Python installation +- [ ] Other: _____ + +## Configuration +Relevant configuration (remove sensitive data): +```yaml +# docker-compose.yml excerpt or .env variables +# DO NOT include passwords or secrets +``` + +## Logs +``` +Paste relevant log output here +``` + +## Additional Context +Add any other context about the problem here. + +## Possible Solution +If you have suggestions on how to fix the issue, please describe them here. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..9692476 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,45 @@ +--- +name: Feature Request +about: Suggest an idea for DMARQ +title: '[FEATURE] ' +labels: 'enhancement' +assignees: '' +--- + +## Feature Description +A clear and concise description of the feature you'd like to see. + +## Problem Statement +Is your feature request related to a problem? Please describe. +Ex. I'm always frustrated when [...] + +## Proposed Solution +Describe the solution you'd like to see implemented. + +## Alternatives Considered +Describe any alternative solutions or features you've considered. + +## Use Case +Describe how this feature would be used and who would benefit from it. + +## Benefits +- Benefit 1 +- Benefit 2 +- Benefit 3 + +## Implementation Ideas +If you have ideas about how this could be implemented, share them here. + +## Related Issues/PRs +Link to any related issues or pull requests. + +## Mockups/Examples +If applicable, add mockups, diagrams, or examples from other tools. + +## Additional Context +Add any other context, screenshots, or information about the feature request here. + +## Checklist +- [ ] I have searched existing issues to ensure this is not a duplicate +- [ ] This feature aligns with DMARQ's mission of privacy-focused DMARC monitoring +- [ ] I am willing to contribute to implementing this feature (optional) diff --git a/.github/ISSUE_TEMPLATE/security_vulnerability.md b/.github/ISSUE_TEMPLATE/security_vulnerability.md new file mode 100644 index 0000000..c8c3c0c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/security_vulnerability.md @@ -0,0 +1,58 @@ +--- +name: Security Vulnerability +about: Report a security issue (CONFIDENTIAL) +title: '[SECURITY] ' +labels: 'security' +assignees: '' +--- + +⚠️ **IMPORTANT: Do not create a public issue for serious security vulnerabilities** + +For serious security vulnerabilities, please email the maintainers directly instead of creating a public issue. See [SECURITY.md](../../SECURITY.md) for contact information. + +--- + +## Security Issue Type +- [ ] Authentication/Authorization issue +- [ ] Data exposure +- [ ] Injection vulnerability (SQL, XSS, etc.) +- [ ] Cryptography issue +- [ ] Dependency vulnerability +- [ ] Configuration security +- [ ] Other: _____ + +## Affected Component +- [ ] Backend API +- [ ] Frontend/UI +- [ ] Database +- [ ] Docker configuration +- [ ] Documentation +- [ ] Dependencies + +## Severity Assessment +- [ ] Critical (immediate action required) +- [ ] High (significant risk) +- [ ] Medium (moderate risk) +- [ ] Low (minor risk) + +## Description +Describe the security issue in detail. + +## Impact +What is the potential impact of this vulnerability? + +## Steps to Reproduce +Provide steps to reproduce the vulnerability. + +## Affected Versions +Which versions of DMARQ are affected? + +## Suggested Remediation +If you have suggestions for fixing the issue, provide them here. + +## References +Links to similar vulnerabilities, CVEs, or relevant documentation. + +--- + +**Remember**: For critical vulnerabilities, use private disclosure via email instead of public issues. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..aa17eba --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,91 @@ +## Description + + +## Related Issue + +Closes #(issue number) + +## Type of Change +- [ ] Bug fix (non-breaking change which fixes an issue) +- [ ] New feature (non-breaking change which adds functionality) +- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) +- [ ] Documentation update +- [ ] Security fix +- [ ] Performance improvement +- [ ] Code refactoring + +## Changes Made + +- Change 1 +- Change 2 +- Change 3 + +## Testing Performed + + +### Test Environment +- Python Version: +- Database: +- OS: + +### Test Steps +1. Step 1 +2. Step 2 +3. Step 3 + +### Test Results + +``` +Paste test results here +``` + +## Screenshots (if applicable) + + +## Security Considerations + +- [ ] This PR has been reviewed for security vulnerabilities +- [ ] No sensitive data is exposed +- [ ] Input validation is implemented +- [ ] Authentication/authorization is properly handled +- [ ] N/A - No security implications + +## Performance Impact + +- [ ] No significant performance impact +- [ ] Performance improved +- [ ] Performance impact acceptable for the functionality +- [ ] Performance concerns (explain below) + +## Documentation +- [ ] Updated relevant documentation +- [ ] Added inline code comments for complex logic +- [ ] Updated API documentation (if applicable) +- [ ] Updated README.md (if applicable) +- [ ] No documentation changes needed + +## Checklist +- [ ] My code follows the style guidelines of this project +- [ ] I have performed a self-review of my code +- [ ] I have commented my code, particularly in hard-to-understand areas +- [ ] I have made corresponding changes to the documentation +- [ ] My changes generate no new warnings or errors +- [ ] I have added tests that prove my fix is effective or that my feature works +- [ ] New and existing unit tests pass locally with my changes +- [ ] Any dependent changes have been merged and published + +## AI Assistance (if applicable) + +- [ ] AI tools were used (GitHub Copilot, Cursor, etc.) +- [ ] All AI-generated code has been reviewed for security and correctness +- [ ] Tests were added for AI-generated code +- [ ] N/A - No AI assistance used + +## Additional Notes + + +## Breaking Changes + + +## Deployment Notes + diff --git a/.github/workflows/security.yml b/.github/workflows/security.yml new file mode 100644 index 0000000..38f119c --- /dev/null +++ b/.github/workflows/security.yml @@ -0,0 +1,99 @@ +name: Security Scanning + +on: + push: + branches: [ main, develop ] + pull_request: + branches: [ main, develop ] + schedule: + # Run weekly on Mondays at 00:00 UTC + - cron: '0 0 * * 1' + +jobs: + security-scan: + name: Security Vulnerability Scan + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: '3.10' + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install bandit safety detect-secrets + cd backend && pip install -r requirements.txt + + - name: Run Bandit (Python Security Linter) + run: | + bandit -r backend/app -f json -o bandit-report.json || true + bandit -r backend/app + continue-on-error: true + + - name: Run Safety (Dependency Vulnerability Check) + run: | + safety check --json || true + safety check + continue-on-error: true + + - name: Run detect-secrets + run: | + detect-secrets scan --baseline .secrets.baseline || true + continue-on-error: true + + - name: Upload Bandit Report + uses: actions/upload-artifact@v3 + if: always() + with: + name: bandit-security-report + path: bandit-report.json + + codeql-analysis: + name: CodeQL Analysis + runs-on: ubuntu-latest + permissions: + actions: read + contents: read + security-events: write + + strategy: + fail-fast: false + matrix: + language: [ 'python' ] + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Initialize CodeQL + uses: github/codeql-action/init@v2 + with: + languages: ${{ matrix.language }} + queries: security-and-quality + + - name: Autobuild + uses: github/codeql-action/autobuild@v2 + + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v2 + with: + category: "/language:${{matrix.language}}" + + dependency-review: + name: Dependency Review + runs-on: ubuntu-latest + if: github.event_name == 'pull_request' + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Dependency Review + uses: actions/dependency-review-action@v3 + with: + fail-on-severity: moderate diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml new file mode 100644 index 0000000..dbed291 --- /dev/null +++ b/.github/workflows/test.yml @@ -0,0 +1,130 @@ +name: Tests + +on: + push: + branches: [ main, develop ] + pull_request: + branches: [ main, develop ] + +jobs: + test: + name: Test Python ${{ matrix.python-version }} + runs-on: ubuntu-latest + + strategy: + matrix: + python-version: ["3.10", "3.11", "3.12"] + + services: + postgres: + image: postgres:14-alpine + env: + POSTGRES_PASSWORD: test_password + POSTGRES_USER: test_user + POSTGRES_DB: test_db + ports: + - 5432:5432 + options: >- + --health-cmd pg_isready + --health-interval 10s + --health-timeout 5s + --health-retries 5 + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Python ${{ matrix.python-version }} + uses: actions/setup-python@v4 + with: + python-version: ${{ matrix.python-version }} + + - name: Cache pip packages + uses: actions/cache@v3 + with: + path: ~/.cache/pip + key: ${{ runner.os }}-pip-${{ hashFiles('backend/requirements.txt') }} + restore-keys: | + ${{ runner.os }}-pip- + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + cd backend + pip install -r requirements.txt + pip install pytest pytest-cov pytest-asyncio + + - name: Run tests with coverage + env: + DATABASE_URL: postgresql://test_user:test_password@localhost:5432/test_db + SECRET_KEY: test_secret_key_for_ci + run: | + cd backend + pytest --cov=app --cov-report=xml --cov-report=term-missing + + - name: Upload coverage to Codecov + uses: codecov/codecov-action@v3 + with: + file: ./backend/coverage.xml + flags: unittests + name: codecov-umbrella + fail_ci_if_error: false + + lint: + name: Lint and Format Check + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: '3.10' + + - name: Install linting tools + run: | + python -m pip install --upgrade pip + pip install pylint black flake8 isort mypy + cd backend && pip install -r requirements.txt + + - name: Run Black (format check) + run: | + black --check backend/app + + - name: Run isort (import order check) + run: | + isort --check-only backend/app + + - name: Run Flake8 + run: | + flake8 backend/app --max-line-length=100 --extend-ignore=E203,W503 + + - name: Run Pylint + run: | + pylint backend/app --max-line-length=100 --disable=C0111,R0903 + continue-on-error: true + + docker-build: + name: Docker Build Test + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v2 + + - name: Build Docker image + run: | + docker compose build + + - name: Test Docker image + run: | + docker compose up -d + sleep 10 + docker compose ps + docker compose logs + docker compose down diff --git a/.gitignore b/.gitignore index 958d4c5..700d3a3 100644 --- a/.gitignore +++ b/.gitignore @@ -185,4 +185,35 @@ cython_debug/ /backend/npm-debug.log* /backend/yarn-debug.log* /backend/yarn-error.log* -/backend/.npm/ \ No newline at end of file +/backend/.npm/ + +# Security scan results +.secrets.baseline +bandit-report.json +security-report.json + +# Database files +*.db +*.sqlite +test.db + +# IDE +.idea/ +.vscode/ +*.swp +*.swo +*~ + +# OS +.DS_Store +Thumbs.db + +# Temporary files +tmp/ +temp/ +*.tmp +*.bak +*.backup + +# Docker override +docker-compose.override.yml \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..8aba023 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,500 @@ +# Agentic Coding Guidelines for DMARQ + +This document provides guidelines for using AI-powered coding assistants (agents) when contributing to DMARQ. Whether you're using GitHub Copilot, Cursor, Claude Code, or other AI coding tools, these guidelines will help you use them effectively and safely. + +## Table of Contents + +- [What is Agentic Coding?](#what-is-agentic-coding) +- [Why DMARQ is Agent-Friendly](#why-dmarq-is-agent-friendly) +- [Getting Started with AI Assistants](#getting-started-with-ai-assistants) +- [Best Practices](#best-practices) +- [Security Considerations](#security-considerations) +- [Effective Prompts](#effective-prompts) +- [Review and Validation](#review-and-validation) +- [Common Pitfalls](#common-pitfalls) + +## What is Agentic Coding? + +Agentic coding refers to software development where AI assistants (agents) help generate, modify, and review code. These tools can: + +- Generate boilerplate code +- Suggest implementations based on comments +- Write tests automatically +- Refactor existing code +- Find and fix bugs +- Generate documentation + +## Why DMARQ is Agent-Friendly + +DMARQ is designed with characteristics that make it work well with AI coding assistants: + +### 1. Clear Architecture +- Modular structure with separation of concerns +- Consistent patterns across the codebase +- Well-defined layers (API, Services, Models) + +### 2. Comprehensive Documentation +- Inline code comments +- API documentation +- Architecture documentation (see `/docs`) +- Clear README with examples + +### 3. Type Hints +```python +def process_report(domain: str, xml_content: str) -> List[Dict[str, Any]]: + """Process a DMARC report with type-safe parameters""" + pass +``` + +### 4. Test Infrastructure +- Existing test patterns to follow +- Clear test organization +- Example tests for reference + +### 5. Consistent Coding Style +- PEP 8 compliance +- Automated formatting with Black +- Clear naming conventions + +## Getting Started with AI Assistants + +### Setting Up Context + +Give your AI assistant context about DMARQ: + +```markdown +DMARQ is a self-hosted DMARC monitoring platform built with: +- Backend: FastAPI (Python 3.10+) +- Database: SQLAlchemy ORM (PostgreSQL/SQLite) +- Templates: Jinja2 with Tailwind CSS +- Architecture: RESTful API with server-side rendering + +Key directories: +- /backend/app/api - API endpoints +- /backend/app/services - Business logic +- /backend/app/models - Database models +- /backend/app/tests - Test files +- /docs - Documentation +``` + +### Provide Examples + +Show the AI assistant examples from the codebase: + +```python +# Example: "Create a new endpoint following this pattern" +@router.get("/domains", response_model=List[DomainResponse]) +async def list_domains(): + """List all monitored domains""" + store = ReportStore.get_instance() + domains = store.get_domains() + return domains +``` + +## Best Practices + +### 1. Start Small + +Begin with small, well-defined tasks: + +✅ **Good**: "Add input validation for the domain parameter" +❌ **Too Broad**: "Rewrite the entire API layer" + +### 2. Iterative Development + +Work in iterations: + +``` +1. Generate initial implementation +2. Review and test +3. Refine based on results +4. Repeat until complete +``` + +### 3. Use AI for Appropriate Tasks + +| Good Use Cases | Proceed with Caution | +|----------------|---------------------| +| Boilerplate code | Security-critical code | +| Test generation | Authentication logic | +| Data models | Cryptography | +| Documentation | Complex algorithms | +| Refactoring | Database migrations | +| Bug fixes | Configuration changes | + +### 4. Provide Clear Specifications + +Be specific in your prompts: + +```markdown +# Good Prompt +Create a new API endpoint `/api/v1/reports/{report_id}` that: +- Returns a single DMARC report by ID +- Uses the existing ReportStore service +- Includes error handling for not-found cases +- Follows the existing endpoint patterns +- Returns a 404 if report doesn't exist +``` + +### 5. Review Generated Code + +**Always** review AI-generated code for: + +- Correctness +- Security vulnerabilities +- Performance implications +- Adherence to project standards +- Test coverage + +## Security Considerations + +### Critical: Security Review Required + +When AI generates code involving: + +- **Authentication/Authorization**: Review thoroughly +- **Input Validation**: Verify all edge cases +- **Database Queries**: Check for SQL injection risks +- **File Operations**: Validate paths and permissions +- **External APIs**: Review credential handling +- **Cryptography**: Verify algorithm choices + +### Security Checklist for AI-Generated Code + +```markdown +- [ ] No hardcoded secrets or credentials +- [ ] All user inputs are validated +- [ ] SQL queries use ORM (no raw SQL) +- [ ] Files are handled securely +- [ ] Error messages don't leak sensitive data +- [ ] Authentication is properly implemented +- [ ] Authorization checks are present +- [ ] HTTPS is enforced where applicable +- [ ] Dependencies are secure versions +``` + +### Example: Reviewing AI-Generated Auth Code + +```python +# ❌ AI might generate this - INSECURE +@router.post("/admin/action") +async def admin_action(): + # Missing authentication check! + return perform_admin_action() + +# ✅ Fixed by human review +@router.post("/admin/action") +async def admin_action( + current_user: User = Depends(get_current_active_user) +): + if not current_user.is_admin: + raise HTTPException(status_code=403, detail="Admin access required") + return perform_admin_action() +``` + +## Effective Prompts + +### Prompt Templates + +#### 1. Creating New Features + +``` +Create a new [feature] that: +- Purpose: [description] +- Location: [file/directory] +- Dependencies: [services, models] +- Follow patterns from: [example file] +- Include: [tests, docs, validation] +- Error handling: [specific requirements] +``` + +#### 2. Fixing Bugs + +``` +Fix the bug in [file] where [description]: +- Current behavior: [what happens now] +- Expected behavior: [what should happen] +- Error message: [if any] +- Reproduce: [steps] +- Maintain: [backward compatibility] +``` + +#### 3. Refactoring + +``` +Refactor [module/function] to [goal]: +- Current issues: [problems] +- Keep: [what must stay the same] +- Improve: [specific aspects] +- Don't break: [tests, APIs] +- Performance: [requirements] +``` + +#### 4. Adding Tests + +``` +Write tests for [function/module]: +- Test file: [location] +- Follow pattern: [existing test] +- Cover cases: [list scenarios] +- Use fixtures: [if applicable] +- Mock: [external dependencies] +``` + +### Real Examples for DMARQ + +```markdown +# Example 1: New Endpoint +Create a GET endpoint /api/v1/domains/{domain}/stats that returns +DMARC statistics for a specific domain. Use the existing DomainResponse +model and ReportStore.get_domain_summary() method. Include error +handling for invalid domain names. + +# Example 2: Input Validation +Add input validation to the domain parameter in the reports upload +endpoint. Domain should match pattern: ^[a-z0-9.-]+$ and be max +255 characters. Return 400 error with clear message if invalid. + +# Example 3: Test Creation +Write pytest tests for the DMARC parser handling compressed files. +Test cases: valid .zip, valid .gz, corrupted archive, empty archive, +archive with multiple files. Place in test_dmarc_parser.py. + +# Example 4: Documentation +Generate API documentation for all endpoints in +/api/v1/endpoints/domains.py following OpenAPI/Swagger format. +Include request/response examples and error codes. +``` + +## Review and Validation + +### Human Review Process + +1. **Read the Code**: Don't just trust, understand it +2. **Test Locally**: Run the code in your environment +3. **Check Tests**: Verify tests are meaningful +4. **Security Scan**: Run security tools (bandit, safety) +5. **Performance**: Consider efficiency implications +6. **Documentation**: Ensure docs are updated + +### Testing AI-Generated Code + +```bash +# Run unit tests +pytest backend/app/tests/ + +# Check code coverage +pytest --cov=app --cov-report=html + +# Lint the code +pylint backend/app/ +black --check backend/app/ + +# Security scan +bandit -r backend/app/ +safety check + +# Type checking +mypy backend/app/ +``` + +### Code Review Questions + +Ask yourself: + +1. **Does it work?** Test thoroughly +2. **Is it secure?** Check for vulnerabilities +3. **Is it maintainable?** Can others understand it? +4. **Does it fit?** Follows project patterns? +5. **Is it tested?** Has adequate test coverage? +6. **Is it documented?** Clear comments and docs? + +## Common Pitfalls + +### Pitfall 1: Over-Trusting AI + +❌ **Don't**: Accept AI code without review +✅ **Do**: Treat AI suggestions as drafts requiring validation + +### Pitfall 2: Insufficient Context + +❌ **Don't**: Give vague prompts +✅ **Do**: Provide specific requirements and examples + +### Pitfall 3: Ignoring Project Standards + +❌ **Don't**: Let AI deviate from project conventions +✅ **Do**: Explicitly mention standards in prompts + +### Pitfall 4: Security Blind Spots + +❌ **Don't**: Assume AI handles security correctly +✅ **Do**: Always perform security review + +### Pitfall 5: Missing Tests + +❌ **Don't**: Ship AI code without tests +✅ **Do**: Generate tests for all new code + +### Pitfall 6: Documentation Lag + +❌ **Don't**: Forget to update documentation +✅ **Do**: Update docs alongside code changes + +## Advanced Techniques + +### 1. Multi-Step Prompting + +Break complex tasks into steps: + +```markdown +Step 1: "Create the data model for forensic reports" +Step 2: "Add database migration for the new model" +Step 3: "Create service methods to process forensic reports" +Step 4: "Add API endpoint to retrieve forensic reports" +Step 5: "Write tests for the entire flow" +``` + +### 2. Using Examples + +Provide examples to guide the AI: + +```python +# "Create a similar endpoint for forensic reports" +# Example to follow: +@router.get("/aggregate-reports/{report_id}") +async def get_aggregate_report(report_id: str): + store = ReportStore.get_instance() + report = store.get_report(report_id) + if not report: + raise HTTPException(status_code=404, detail="Report not found") + return report +``` + +### 3. Constraint-Based Generation + +Set clear boundaries: + +```markdown +Create a caching layer for domain statistics: +- Must not cache for more than 5 minutes +- Must handle cache invalidation on new reports +- Must be thread-safe +- Must use Redis if available, fallback to in-memory +- Must include cache hit/miss metrics +``` + +### 4. Validation Prompts + +Ask AI to review its own work: + +```markdown +Review the above code for: +1. Security vulnerabilities +2. Performance bottlenecks +3. Error handling completeness +4. Test coverage gaps +5. Documentation clarity +``` + +## Integration with Development Workflow + +### Git Workflow + +```bash +# 1. Create branch +git checkout -b feature/ai-assisted-forensic-reports + +# 2. Use AI to generate code +# ... work with AI assistant ... + +# 3. Review and test +pytest +bandit -r backend/app/ + +# 4. Commit with clear message +git commit -m "feat: add forensic report support + +Generated initial implementation with AI assistance. +Manually reviewed for security and correctness. +Added additional test cases and error handling." + +# 5. Create PR with context +# Mention AI assistance in PR description +``` + +### PR Description Template + +```markdown +## Description +[What was changed] + +## AI Assistance +- Tool used: GitHub Copilot / Cursor / Claude +- Tasks assisted: [code generation, tests, docs] +- Human review: [what you validated] + +## Testing +[How you tested the AI-generated code] + +## Security Review +- [ ] No hardcoded secrets +- [ ] Input validation present +- [ ] Authentication/authorization correct +- [ ] No SQL injection risks +- [ ] Error handling appropriate +``` + +## Resources + +### AI Coding Tools + +- **GitHub Copilot**: https://github.com/features/copilot +- **Cursor**: https://cursor.sh/ +- **Tabnine**: https://www.tabnine.com/ +- **Amazon CodeWhisperer**: https://aws.amazon.com/codewhisperer/ + +### Security Tools + +```bash +# Install security scanning tools +pip install bandit safety detect-secrets + +# Run scans +bandit -r backend/app/ +safety check +detect-secrets scan +``` + +### Learning Resources + +- [GitHub Copilot Best Practices](https://github.blog/2023-06-20-how-to-write-better-prompts-for-github-copilot/) +- [AI-Assisted Coding Security Guide](https://owasp.org/www-project-ai-security-and-privacy-guide/) +- [DMARQ Contributing Guide](CONTRIBUTING.md) +- [DMARQ Security Policy](SECURITY.md) + +## Questions and Support + +If you have questions about using AI assistants with DMARQ: + +1. Check this guide first +2. Review existing AI-assisted PRs for examples +3. Ask in GitHub Discussions +4. Mention in your PR if you need guidance + +## Conclusion + +AI coding assistants are powerful tools that can accelerate development when used properly. The key principles: + +1. **AI assists, humans decide**: You're responsible for the code +2. **Security first**: Always review for vulnerabilities +3. **Test everything**: Don't trust, verify +4. **Document clearly**: Note when AI was used +5. **Follow standards**: Maintain project consistency + +Happy coding with your AI assistant! 🤖✨ + +--- + +**Document Version**: 1.0 +**Last Updated**: 2026-02-06 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..88330ce --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,464 @@ +# Contributing to DMARQ + +First off, thank you for considering contributing to DMARQ! It's people like you that make DMARQ such a great tool for DMARC monitoring and email security. + +## Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [How Can I Contribute?](#how-can-i-contribute) +- [Development Setup](#development-setup) +- [Making Changes](#making-changes) +- [Testing](#testing) +- [Style Guidelines](#style-guidelines) +- [Commit Messages](#commit-messages) +- [Pull Request Process](#pull-request-process) +- [Security](#security) + +## Code of Conduct + +This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainers. + +## How Can I Contribute? + +### Reporting Bugs + +Before creating bug reports, please check the existing issues list as you might find that you don't need to create one. When you are creating a bug report, please include as many details as possible: + +- **Use a clear and descriptive title** +- **Describe the exact steps to reproduce the problem** +- **Provide specific examples** to demonstrate the steps +- **Describe the behavior you observed** and what you expected +- **Include screenshots** if relevant +- **Include your environment details** (OS, Python version, Docker version) + +### Suggesting Enhancements + +Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion: + +- **Use a clear and descriptive title** +- **Provide a detailed description** of the proposed feature +- **Explain why this enhancement would be useful** +- **List some examples** of how it would be used +- **Consider the scope** - does it fit DMARQ's mission? + +### Your First Code Contribution + +Unsure where to begin? You can start by looking through issues tagged with: + +- `good first issue` - should only require a few lines of code +- `help wanted` - more involved but not requiring deep knowledge of the codebase +- `documentation` - improvements or additions to documentation + +### Pull Requests + +- Fill in the required template +- Follow the [style guidelines](#style-guidelines) +- Include tests when adding features +- Update documentation as needed +- End all files with a newline + +## Development Setup + +### Prerequisites + +- Python 3.10 or higher +- Docker and Docker Compose (for full stack testing) +- Git + +### Local Development Setup + +1. **Fork and clone the repository** + +```bash +git clone https://github.com/YOUR_USERNAME/dmarq.git +cd dmarq +``` + +2. **Set up Python virtual environment** + +```bash +cd backend +python -m venv venv +source venv/bin/activate # On Windows: venv\Scripts\activate +pip install -r requirements.txt +pip install -r requirements-dev.txt # Development dependencies +``` + +3. **Set up environment variables** + +```bash +cp .env.example .env +# Edit .env with your local configuration +``` + +4. **Run the development server** + +```bash +cd backend +uvicorn app.main:app --reload --port 8080 +``` + +5. **Access the application** + +Open your browser to http://localhost:8080 + +### Docker Development + +For a full stack with database: + +```bash +docker compose up --build +``` + +## Making Changes + +### Branch Naming Convention + +Use descriptive branch names: + +- `feature/add-new-chart-type` +- `fix/imap-connection-error` +- `docs/update-api-documentation` +- `security/fix-xss-vulnerability` + +### Development Workflow + +1. **Create a new branch** + +```bash +git checkout -b feature/your-feature-name +``` + +2. **Make your changes** + - Write clear, concise code + - Follow the style guidelines + - Add tests for new functionality + - Update documentation + +3. **Test your changes** + +```bash +# Run unit tests +pytest + +# Run with coverage +pytest --cov=app --cov-report=html + +# Run linting +pylint app/ +flake8 app/ +black --check app/ + +# Run security checks +bandit -r app/ +safety check +``` + +4. **Commit your changes** + +```bash +git add . +git commit -m "feat: add new feature" +``` + +5. **Push to your fork** + +```bash +git push origin feature/your-feature-name +``` + +6. **Create a Pull Request** + +## Testing + +### Running Tests + +```bash +# Run all tests +pytest + +# Run specific test file +pytest backend/app/tests/test_dmarc_parser.py + +# Run with verbose output +pytest -v + +# Run with coverage report +pytest --cov=app --cov-report=term-missing +``` + +### Writing Tests + +- Place tests in `backend/app/tests/` +- Name test files with `test_` prefix +- Name test functions with `test_` prefix +- Use descriptive test names that explain what is being tested + +Example: + +```python +def test_dmarc_parser_handles_valid_xml(): + """Test that the parser correctly processes valid DMARC XML""" + parser = DMARCParser() + result = parser.parse_xml(valid_xml_content) + assert result is not None + assert result['domain'] == 'example.com' +``` + +### Test Coverage Goals + +- Aim for at least 80% code coverage +- Critical security features should have 100% coverage +- All new features must include tests + +## Style Guidelines + +### Python Style Guide + +We follow PEP 8 with some modifications: + +- **Line length**: Maximum 100 characters (not 79) +- **Imports**: Organize as stdlib, third-party, local +- **Docstrings**: Use Google-style docstrings +- **Type hints**: Use type hints for function signatures + +Example: + +```python +from typing import Optional, List +from datetime import datetime + +def process_dmarc_report( + domain: str, + report_xml: str, + timestamp: Optional[datetime] = None +) -> List[dict]: + """ + Process a DMARC aggregate report. + + Args: + domain: The domain name being reported on + report_xml: Raw XML content of the DMARC report + timestamp: Optional timestamp for the report + + Returns: + List of processed report records + + Raises: + ValueError: If the XML is malformed + """ + # Implementation here + pass +``` + +### Code Formatting + +We use automated code formatters: + +```bash +# Format code with black +black backend/app/ + +# Sort imports with isort +isort backend/app/ + +# Type checking with mypy (coming soon) +mypy backend/app/ +``` + +### Documentation Style + +- Use clear, concise language +- Include code examples where helpful +- Keep documentation up-to-date with code changes +- Use proper Markdown formatting + +## Commit Messages + +Follow the Conventional Commits specification: + +### Format + +``` +(): + + + +