Add comprehensive security and contribution documentation

Co-authored-by: christianlouis <361235+christianlouis@users.noreply.github.com>
2026-02-06 22:00:17 +00:00
parent 53f20f25d1
commit 9ae57b2a8f
14 changed files with 2417 additions and 1 deletions
@@ -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
@@ -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.
@@ -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)
@@ -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.
@@ -0,0 +1,91 @@
 ## Description
 <!-- Provide a clear and concise description of what this PR does -->
 ## Related Issue
 <!-- Link to the issue this PR addresses -->
 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
 <!-- List the main changes made in this PR -->
 - Change 1
 - Change 2
 - Change 3
 ## Testing Performed
 <!-- Describe the tests you ran to verify your changes -->
 ### Test Environment
 - Python Version: 
 - Database: 
 - OS: 
 ### Test Steps
 1. Step 1
 2. Step 2
 3. Step 3
 ### Test Results
 <!-- Paste test output or describe results -->
 ```
 Paste test results here
 ```
 ## Screenshots (if applicable)
 <!-- Add screenshots to demonstrate UI changes -->
 ## Security Considerations
 <!-- For security-related changes, describe security implications -->
 - [ ] 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
 <!-- Describe any performance implications -->
 - [ ] 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)
 <!-- If you used AI coding assistants, please note it here -->
 - [ ] 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
 <!-- Any additional information that reviewers should know -->
 ## Breaking Changes
 <!-- If this is a breaking change, describe what breaks and migration steps -->
 ## Deployment Notes
 <!-- Special deployment considerations or database migrations required -->
@@ -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
@@ -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
@@ -185,4 +185,35 @@ cython_debug/
 /backend/npm-debug.log*
 /backend/yarn-debug.log*
 /backend/yarn-error.log*
-/backend/.npm/
+/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
@@ -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
@@ -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
 ```
 <type>(<scope>): <subject>
 <body>
 <footer>
 ```
 ### Types
 - `feat`: A new feature
 - `fix`: A bug fix
 - `docs`: Documentation only changes
 - `style`: Code style changes (formatting, missing semicolons, etc.)
 - `refactor`: Code change that neither fixes a bug nor adds a feature
 - `perf`: Performance improvements
 - `test`: Adding missing tests or correcting existing tests
 - `chore`: Changes to build process or auxiliary tools
 - `security`: Security improvements or fixes
 ### Examples
 ```
 feat(parser): add support for forensic DMARC reports
 Added parsing logic for DMARC forensic (failure) reports (RUF).
 This allows users to see detailed information about individual
 email authentication failures.
 Closes #123
 ```
 ```
 fix(imap): handle connection timeout gracefully
 The IMAP client now properly handles timeout exceptions and
 retries with exponential backoff. This prevents the application
 from crashing when the mail server is temporarily unavailable.
 Fixes #456
 ```
 ```
 security(api): add authentication to admin endpoints
 Added authentication checks to /api/v1/admin/* endpoints to
 prevent unauthorized access.
 BREAKING CHANGE: Admin endpoints now require authentication token
 ```
 ## Pull Request Process
 ### Before Submitting
 1. **Ensure your code follows the style guidelines**
 2. **Run all tests and ensure they pass**
 3. **Update documentation** as necessary
 4. **Add or update tests** for your changes
 5. **Run security scans** if touching sensitive code
 6. **Verify the application works** with your changes
 ### PR Template
 When you create a PR, fill out the template completely:
 ```markdown
 ## Description
 Brief description of the changes
 ## 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
 ## Testing
 Describe the tests you ran and how to reproduce them
 ## Checklist
 - [ ] My code follows the style guidelines
 - [ ] 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
 - [ ] 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
 ```
 ### Review Process
 1. **Automated checks** must pass (linting, tests, security scans)
 2. **At least one maintainer review** is required
 3. **Address review comments** promptly and professionally
 4. **Keep the PR focused** - one feature/fix per PR
 5. **Be patient** - maintainers review PRs as time allows
 ### After Approval
 Once approved, a maintainer will merge your PR. The merge will trigger:
 - Automated deployment (if applicable)
 - Documentation updates
 - Release notes generation
 ## Security
 ### Reporting Security Issues
 **DO NOT** create public issues for security vulnerabilities. Instead:
 1. Email the maintainers (see SECURITY.md for contact info)
 2. Provide detailed information about the vulnerability
 3. Allow time for the issue to be addressed before public disclosure
 ### Security Best Practices
 When contributing code that touches security-sensitive areas:
 - **Never commit secrets** (API keys, passwords, etc.)
 - **Validate all inputs** from users or external systems
 - **Use parameterized queries** (our ORM does this automatically)
 - **Follow principle of least privilege**
 - **Add security tests** for authentication/authorization changes
 - **Document security implications** in your PR
 ### Security Checklist for PRs
 If your PR involves any of these, extra scrutiny is required:
 - [ ] Authentication or authorization
 - [ ] Data validation or sanitization
 - [ ] Database queries
 - [ ] File uploads or downloads
 - [ ] External API calls
 - [ ] Cryptography or password handling
 - [ ] Configuration or environment variables
 ## Working with AI Assistants (Agentic Coding)
 DMARQ is designed to be "agentic coding friendly" - meaning it works well with AI coding assistants like GitHub Copilot, Cursor, and similar tools.
 ### Tips for AI-Assisted Development
 1. **Clear Context**: Ensure your AI assistant has context about DMARQ's architecture
 2. **Security First**: Always review AI-generated code for security implications
 3. **Test Coverage**: AI-generated code still needs tests
 4. **Code Review**: Human review is essential for AI-generated contributions
 5. **Documentation**: Update docs even for AI-assisted changes
 ### Prompts that Work Well
 When using AI assistants, these patterns work well:
 ```
 "Add a new API endpoint to [do something], following DMARQ's existing patterns in the api/ directory"
 "Write tests for [functionality] using the existing test structure in tests/"
 "Refactor [module] to improve [aspect] while maintaining backward compatibility"
 "Add input validation for [endpoint] following DMARQ's security guidelines"
 ```
 ## Questions?
 If you have questions about contributing:
 - Check the [documentation](https://dmarq.readthedocs.io/)
 - Search [existing issues](https://github.com/christianlouis/dmarq/issues)
 - Join our community [discussions](https://github.com/christianlouis/dmarq/discussions)
 - Ask in your PR - maintainers are happy to help!
 ## Recognition
 Contributors are recognized in:
 - The project README
 - Release notes
 - The contributors page (coming soon)
 Thank you for making DMARQ better! 🎉
@@ -0,0 +1,418 @@
 # DMARQ Security-Enhanced Roadmap
 ## Document Purpose
 This roadmap outlines the development plan for DMARQ with an enhanced focus on security, code quality, and preparation for agentic coding (AI-assisted development). This document supersedes previous roadmap versions with security milestones integrated throughout.
 **Last Updated**: 2026-02-06  
 **Status**: Active Development
 ---
 ## Current Status (Milestone 1 - COMPLETE ✅)
 ### Achievements
 - ✅ Basic DMARC report parsing (XML, ZIP, GZIP)
 - ✅ In-memory storage for up to 5 domains
 - ✅ Simple dashboard UI
 - ✅ Report upload functionality
 - ✅ Domain overview with compliance stats
 ### Security Status
 ⚠️ **Multiple critical security issues identified** - See [SECURITY.md](../SECURITY.md) for details
 ---
 ## Security Remediation Sprint (PRIORITY - In Progress)
 **Timeline**: Immediate (Next 2-4 weeks)  
 **Status**: 🔄 In Progress
 ### Critical Fixes Required
 #### 1. Authentication & Authorization (CRITICAL)
 - [ ] Add authentication middleware to all admin endpoints
 - [ ] Implement proper user authentication system
 - [ ] Add authorization checks on sensitive operations
 - [ ] Add rate limiting to prevent abuse
 - **Files to Fix**:
  - `backend/app/main.py` (lines 195-196, 224-225)
  - `backend/app/api/api_v1/endpoints/imap.py`
  - `backend/app/api/api_v1/endpoints/domains.py`
 #### 2. Secret Management (CRITICAL)
 - [ ] Remove default SECRET_KEY value
 - [ ] Add SECRET_KEY validation on startup
 - [ ] Document secret generation in deployment guide
 - [ ] Add warning if default secret is detected
 - **Files to Fix**:
  - `backend/app/core/config.py` (line 24)
  - Documentation updates
 #### 3. XML Parsing Security (HIGH)
 - [ ] Replace ElementTree with defusedxml
 - [ ] Add file size limits for uploads
 - [ ] Implement zip bomb protection
 - [ ] Add malware scanning hooks (optional)
 - **Files to Fix**:
  - `backend/app/services/dmarc_parser.py`
 #### 4. Input Validation (HIGH)
 - [ ] Add domain name validation regex
 - [ ] Implement file type validation (MIME + extension)
 - [ ] Add parameter validation on all endpoints
 - [ ] Sanitize error messages
 - **Files to Fix**:
  - `backend/app/api/api_v1/endpoints/domains.py`
  - `backend/app/api/api_v1/endpoints/reports.py`
  - `backend/app/utils/domain_validator.py`
 #### 5. Security Headers (MEDIUM)
 - [ ] Add security headers middleware
 - [ ] Implement CSP (Content Security Policy)
 - [ ] Add X-Frame-Options, X-Content-Type-Options
 - [ ] Configure HSTS for production
 - **Files to Create/Modify**:
  - `backend/app/middleware/security.py` (new)
  - `backend/app/main.py`
 #### 6. CORS Configuration (MEDIUM)
 - [ ] Restrict CORS methods and headers
 - [ ] Remove wildcard configurations
 - [ ] Document CORS setup for deployments
 - **Files to Fix**:
  - `backend/app/main.py` (lines 75-82)
 #### 7. Error Handling (MEDIUM)
 - [ ] Implement centralized error handling
 - [ ] Remove sensitive data from error responses
 - [ ] Add error logging with request context
 - [ ] Create user-friendly error messages
 - **Files to Fix**:
  - Multiple endpoints across API layer
 ### Testing & Validation
 - [ ] Add security-focused unit tests
 - [ ] Implement integration tests for auth flow
 - [ ] Add penetration testing checklist
 - [ ] Document security testing procedures
 ### Documentation
 - [x] Create SECURITY.md
 - [ ] Update deployment guides with security best practices
 - [ ] Create security checklist for contributors
 - [ ] Add security section to API documentation
 ---
 ## Milestone 2: IMAP Integration (COMPLETE ✅ - Security Review Needed)
 ### Current Features
 - ✅ IMAP connection and mailbox scanning
 - ✅ Automated report fetching
 - ✅ Background task scheduler
 - ✅ Configuration UI
 ### Security Enhancements Needed
 - [ ] **URGENT**: Remove credentials from URL parameters
 - [ ] Encrypt IMAP credentials at rest
 - [ ] Add connection timeout and retry logic
 - [ ] Implement secure credential storage (vault integration)
 - [ ] Add audit logging for IMAP operations
 ---
 ## Milestone 3: Database Integration & Persistence (COMPLETE ✅)
 ### Current Features
 - ✅ SQLAlchemy ORM setup
 - ✅ SQLite/PostgreSQL support
 - ✅ Database migrations with Alembic
 - ✅ Persistent storage
 ### Security Enhancements Needed
 - [ ] Add database encryption at rest
 - [ ] Implement query audit logging
 - [ ] Add prepared statement validation
 - [ ] Review and secure database credentials
 - [ ] Add database backup encryption
 ---
 ## Milestone 4: Enhanced Dashboard & Visualization (Next - 4-6 weeks)
 ### Planned Features
 - [ ] Historical trend charts (Chart.js integration)
 - [ ] Compliance rate visualizations
 - [ ] Volume and sender analytics
 - [ ] Time-series data displays
 - [ ] Domain comparison views
 ### Security Considerations
 - [ ] XSS prevention in chart data
 - [ ] CSP compatibility with Chart.js
 - [ ] Rate limiting on analytics endpoints
 - [ ] Data access controls for multi-user scenarios
 ### Implementation
 - **Priority**: Medium
 - **Dependencies**: Security Sprint completion
 - **Estimated Effort**: 2-3 weeks
 ---
 ## Milestone 5: User Authentication & Multi-User Support (8-10 weeks)
 ### Planned Features
 - [ ] FastAPI Users integration
 - [ ] User registration and management
 - [ ] JWT-based authentication
 - [ ] Role-based access control (RBAC)
 - [ ] Password reset functionality
 - [ ] Email verification (optional)
 ### Security Features
 - [ ] Strong password policy enforcement
 - [ ] Multi-factor authentication (MFA)
 - [ ] Session management
 - [ ] Account lockout on failed attempts
 - [ ] Security event logging
 - [ ] GDPR compliance features
 ### Implementation Priority
 - **Priority**: High
 - **Security Impact**: Critical
 - **Dependencies**: Security Sprint, Milestone 4
 ---
 ## Milestone 6: Alerting & Notifications (10-12 weeks)
 ### Planned Features
 - [ ] Apprise integration
 - [ ] Customizable alert rules
 - [ ] Multi-channel notifications (Email, Slack, etc.)
 - [ ] Alert history and management
 - [ ] Notification preferences per user
 ### Security Features
 - [ ] Secure webhook handling
 - [ ] Alert rate limiting
 - [ ] PII filtering in notifications
 - [ ] Encrypted notification credentials
 - [ ] Audit trail for alert configuration
 ---
 ## Milestone 7: Advanced Rule Engine (14-16 weeks)
 ### Planned Features
 - [ ] Custom alert conditions
 - [ ] Threshold-based triggers
 - [ ] New sender detection
 - [ ] Anomaly detection
 - [ ] Scheduled report summaries
 ### Security Features
 - [ ] Rule validation and sandboxing
 - [ ] Resource limits on rule execution
 - [ ] Audit logging for rule changes
 - [ ] Protection against rule abuse
 ---
 ## Milestone 8: DNS Health & Cloudflare Integration (16-18 weeks)
 ### Planned Features
 - [ ] DNS record health checks
 - [ ] SPF/DKIM/DMARC validation
 - [ ] Cloudflare API integration
 - [ ] Configuration recommendations
 - [ ] DNS change tracking
 ### Security Features
 - [ ] Secure API credential storage
 - [ ] DNS query rate limiting
 - [ ] DNSSEC validation
 - [ ] Audit logging for DNS operations
 - [ ] Read-only DNS access (no auto-changes initially)
 ---
 ## Milestone 9: Forensic Reports (RUF) Support (20-22 weeks)
 ### Planned Features
 - [ ] Forensic report parsing
 - [ ] Failure sample analysis
 - [ ] PII redaction options
 - [ ] Detailed authentication failure views
 - [ ] Sample download/export
 ### Security Features
 - [ ] PII detection and redaction
 - [ ] Access controls for sensitive data
 - [ ] Audit logging for forensic data access
 - [ ] Compliance with privacy regulations
 - [ ] Secure export with encryption
 ---
 ## Milestone 10: Advanced Analytics & Reporting (24-26 weeks)
 ### Planned Features
 - [ ] Historical trend analysis
 - [ ] Comparative reporting
 - [ ] Export capabilities (PDF, CSV)
 - [ ] Scheduled reports
 - [ ] Custom dashboards
 ### Security Features
 - [ ] Export sanitization
 - [ ] Watermarking for exported reports
 - [ ] Access logging for exports
 - [ ] Encrypted export files
 ---
 ## Milestone 11: Enterprise Features (28-30+ weeks)
 ### Planned Features
 - [ ] Multi-tenant architecture
 - [ ] API rate limiting
 - [ ] Advanced RBAC
 - [ ] SSO integration (SAML, OAuth)
 - [ ] Compliance reporting (SOC 2, GDPR)
 - [ ] High availability setup
 - [ ] Backup and disaster recovery
 ### Security Features
 - [ ] Tenant isolation
 - [ ] Advanced audit logging
 - [ ] Security event monitoring
 - [ ] Compliance automation
 - [ ] Regular security assessments
 ---
 ## Continuous Improvements (Ongoing)
 ### Code Quality
 - [ ] Maintain >80% test coverage
 - [ ] Regular dependency updates
 - [ ] Code review for all changes
 - [ ] Performance optimization
 - [ ] Technical debt reduction
 ### Security
 - [ ] Monthly security audits
 - [ ] Automated vulnerability scanning (GitHub Actions)
 - [ ] Dependency security monitoring
 - [ ] Regular penetration testing
 - [ ] Security training for contributors
 ### Documentation
 - [ ] Keep documentation current
 - [ ] API documentation completeness
 - [ ] Security best practices guide
 - [ ] Deployment playbooks
 - [ ] Troubleshooting guides
 ### Community
 - [ ] Issue triage and response
 - [ ] PR review and merging
 - [ ] Community engagement
 - [ ] Feature request evaluation
 - [ ] Bug fix prioritization
 ---
 ## Security Milestones Integration
 Each development milestone now includes security considerations:
 | Milestone | Security Priority | Key Security Features |
 |-----------|------------------|----------------------|
 | Security Sprint | 🔴 Critical | Fix all critical vulnerabilities |
 | Milestone 4 | 🟡 Medium | XSS prevention, CSP |
 | Milestone 5 | 🔴 Critical | Authentication, RBAC, MFA |
 | Milestone 6 | 🟠 High | Secure webhooks, PII filtering |
 | Milestone 7 | 🟠 High | Rule sandboxing, audit trails |
 | Milestone 8 | 🟠 High | API security, DNSSEC |
 | Milestone 9 | 🔴 Critical | PII redaction, compliance |
 | Milestone 10 | 🟡 Medium | Export security, watermarking |
 | Milestone 11 | 🔴 Critical | Enterprise security, SOC 2 |
 ---
 ## Success Criteria
 ### Functional
 - All planned features implemented
 - Performance meets requirements
 - User experience is intuitive
 - Documentation is complete
 ### Security
 - Zero critical vulnerabilities
 - All high-severity issues resolved
 - Security tests pass
 - Regular security audits pass
 - Compliance requirements met
 ### Quality
 - >80% code coverage
 - All tests passing
 - No critical bugs
 - Performance benchmarks met
 - Code review approval
 ---
 ## Risk Management
 ### Technical Risks
 - **Risk**: Complex security implementations
  - **Mitigation**: Incremental approach, expert review
 - **Risk**: Performance degradation with security features
  - **Mitigation**: Performance testing, optimization
 ### Resource Risks
 - **Risk**: Limited security expertise
  - **Mitigation**: External security audits, community review
 - **Risk**: Time constraints for security work
  - **Mitigation**: Prioritize critical issues first
 ### Operational Risks
 - **Risk**: Breaking changes with security fixes
  - **Mitigation**: Thorough testing, clear documentation
 - **Risk**: User adoption of security features
  - **Mitigation**: Clear communication, good UX
 ---
 ## Contributing to This Roadmap
 This roadmap is a living document. To contribute:
 1. Review current milestones and status
 2. Propose changes via GitHub Issues
 3. Discuss in community forums
 4. Submit PRs for roadmap updates
 5. Participate in planning discussions
 See [CONTRIBUTING.md](../CONTRIBUTING.md) for detailed guidelines.
 ---
 ## References
 - [SECURITY.md](../SECURITY.md) - Security policy and vulnerability reporting
 - [CONTRIBUTING.md](../CONTRIBUTING.md) - Contribution guidelines
 - [AGENTS.md](../AGENTS.md) - AI-assisted development guidelines
 - [docs/milestones.md](milestones.md) - Detailed milestone specifications
 - [docs/todo.md](todo.md) - Detailed task tracking
 ---
 **Maintained by**: DMARQ Development Team  
 **Contact**: See [SECURITY.md](../SECURITY.md) for contact information
@@ -0,0 +1,324 @@
 # Security Policy
 ## Overview
 DMARQ is a privacy-conscious, self-hosted DMARC monitoring and analysis platform. Security is paramount given that this tool processes sensitive email authentication data. This document outlines our security policy, how to report vulnerabilities, and security best practices for deployments.
 ## Supported Versions
 We currently support security updates for the following versions:
 | Version | Supported          |
 | ------- | ------------------ |
 | 0.1.x   | :white_check_mark: |
 ## Reporting a Vulnerability
 We take all security vulnerabilities seriously. If you discover a security vulnerability in DMARQ, please follow these steps:
 ### How to Report
 1. **DO NOT** create a public GitHub issue for security vulnerabilities
 2. Email security reports to: [Maintainer Email - TODO: Add email address]
 3. Include the following information:
   - Description of the vulnerability
   - Steps to reproduce the issue
   - Potential impact
   - Suggested fix (if any)
 ### What to Expect
 - **Initial Response**: Within 48 hours of submission
 - **Status Update**: Regular updates every 5-7 days
 - **Resolution Timeline**: We aim to address critical vulnerabilities within 7 days
 - **Credit**: Security researchers will be credited in our release notes (unless you prefer to remain anonymous)
 ## Known Security Considerations
 ### Critical Security Issues Identified (Status: Pending Remediation)
 The following security issues have been identified and are documented for transparency:
 #### 1. **Missing Authentication on Admin Endpoints** (CRITICAL)
 - **Location**: `backend/app/main.py` lines 195-196, 224-225
 - **Issue**: Admin endpoints `/api/v1/admin/trigger-poll` and `/api/v1/admin/poll-status` lack authentication
 - **Impact**: Unauthorized users can trigger IMAP polling operations
 - **Status**: ⚠️ Requires immediate remediation
 - **Workaround**: Use network-level access controls to restrict access
 #### 2. **Default SECRET_KEY in Configuration** (CRITICAL)
 - **Location**: `backend/app/core/config.py` line 24
 - **Issue**: Default SECRET_KEY value is not production-safe
 - **Impact**: JWT tokens can be forged if default key is used
 - **Status**: ⚠️ Must be changed before production deployment
 - **Remediation**: Always set a unique `SECRET_KEY` in your `.env` file using a cryptographically secure random string
 #### 3. **XML External Entity (XXE) Vulnerability** (HIGH)
 - **Location**: `backend/app/services/dmarc_parser.py`
 - **Issue**: Standard ElementTree parser used instead of defusedxml
 - **Impact**: Potential XXE attacks through malicious DMARC reports
 - **Status**: ⚠️ Requires code changes
 - **Mitigation**: Use `defusedxml.ElementTree` instead of standard library
 #### 4. **IMAP Credentials in URLs** (HIGH)
 - **Location**: `backend/app/api/api_v1/endpoints/imap.py`
 - **Issue**: IMAP credentials accepted as query parameters
 - **Impact**: Credentials exposed in logs and browser history
 - **Status**: ⚠️ Requires API redesign
 - **Workaround**: Only use environment variables for IMAP configuration
 #### 5. **Insufficient File Upload Validation** (HIGH)
 - **Location**: `backend/app/api/api_v1/endpoints/reports.py`
 - **Issue**: File type validation relies only on extensions
 - **Impact**: Malicious files may bypass detection
 - **Status**: ⚠️ Requires enhanced validation
 - **Mitigation**: Implement MIME type checking and content validation
 #### 6. **Missing Security Headers** (MEDIUM)
 - **Location**: `backend/app/main.py`
 - **Issue**: No security headers configured (CSP, X-Frame-Options, etc.)
 - **Impact**: Increased XSS and clickjacking risks
 - **Status**: 🔄 Enhancement needed
 #### 7. **Overly Permissive CORS Configuration** (MEDIUM)
 - **Location**: `backend/app/main.py` lines 75-82
 - **Issue**: Wildcard methods and headers allowed
 - **Impact**: Potential CSRF and security bypass issues
 - **Status**: 🔄 Should be restricted
 #### 8. **Exception Details Exposed to Clients** (MEDIUM)
 - **Location**: Multiple endpoints
 - **Issue**: Full exception messages returned in API responses
 - **Impact**: Information disclosure to potential attackers
 - **Status**: 🔄 Needs error handling improvements
 ## Security Best Practices for Deployment
 ### 1. Environment Configuration
 **Always configure these security-critical settings:**
 ```bash
 # Generate a secure secret key (use a tool like openssl)
 SECRET_KEY=$(openssl rand -hex 32)
 # Use strong database credentials
 DATABASE_URL=postgresql://user:strong_password@localhost/dmarq
 # Secure IMAP credentials
 IMAP_PASSWORD=your_secure_password
 # Configure proper CORS origins (no wildcards)
 BACKEND_CORS_ORIGINS=https://your-domain.com
 ```
 ### 2. Network Security
 - **Run behind a reverse proxy** (nginx, Traefik, Caddy) with TLS
 - **Restrict network access** to the database and IMAP services
 - **Use firewall rules** to limit access to trusted networks
 - **Enable HTTPS only** - never expose the application over plain HTTP
 ### 3. Database Security
 - Use PostgreSQL instead of SQLite for production
 - Enable database encryption at rest
 - Use strong, unique passwords
 - Regular database backups with encryption
 - Limit database user permissions (principle of least privilege)
 ### 4. File Upload Security
 - Validate file extensions AND content types
 - Implement file size limits (configured in your reverse proxy)
 - Store uploaded files outside the webroot
 - Scan uploaded files for malware (integrate with ClamAV or similar)
 ### 5. Docker Security
 ```yaml
 # docker-compose.yml security best practices
 services:
  app:
    security_opt:
      - no-new-privileges:true
    read_only: true
    tmpfs:
      - /tmp
    user: "1000:1000"  # Run as non-root user
 ```
 ### 6. Monitoring and Logging
 - Enable application logging and monitor for suspicious activity
 - Use log aggregation (ELK stack, Loki, etc.)
 - Set up alerts for:
  - Failed authentication attempts
  - Unusual API access patterns
  - File upload errors
  - IMAP connection failures
 - Regularly review logs for security incidents
 ### 7. Regular Updates
 - Keep Docker images updated
 - Update Python dependencies regularly
 - Monitor security advisories for FastAPI and dependencies
 - Apply security patches promptly
 ### 8. Access Control
 - Implement role-based access control (RBAC) when multi-user support is added
 - Use strong password policies (minimum length, complexity)
 - Enable multi-factor authentication (MFA) when available
 - Regular audit of user accounts and permissions
 ## Security Development Practices
 ### For Contributors
 1. **Never commit secrets** to the repository
 2. **Use `.env` files** for local development (never commit `.env`)
 3. **Follow secure coding guidelines**:
   - Validate all user inputs
   - Use parameterized queries (SQLAlchemy ORM handles this)
   - Escape output in templates (Jinja2 auto-escapes by default)
   - Use HTTPS for all external API calls
 4. **Add security tests** for new features
 5. **Run security scans** before submitting PRs:
   ```bash
   # Check for hardcoded secrets
   pip install detect-secrets
   detect-secrets scan
   # Check for known vulnerabilities
   pip install safety
   safety check
   # Static analysis
   pip install bandit
   bandit -r backend/app
   ```
 ### Code Review Checklist
 Before approving PRs, reviewers should verify:
 - [ ] No hardcoded credentials or secrets
 - [ ] Input validation on all user-supplied data
 - [ ] Authentication/authorization checks on sensitive endpoints
 - [ ] Proper error handling (no sensitive data in error messages)
 - [ ] SQL injection prevention (using ORM properly)
 - [ ] XSS prevention (output escaping)
 - [ ] CSRF protection where applicable
 - [ ] Secure file handling (if files are uploaded/downloaded)
 - [ ] Dependencies are up-to-date and without known vulnerabilities
 ## Secure Configuration Template
 Create a production-ready `.env` file using this template:
 ```bash
 # Application Settings (REQUIRED)
 PROJECT_NAME="DMARQ"
 SECRET_KEY="GENERATE_UNIQUE_KEY_HERE_USE_OPENSSL_RAND_HEX_32"
 ENVIRONMENT="production"
 # Database (REQUIRED - Use PostgreSQL in production)
 DATABASE_URL="postgresql://dmarq_user:STRONG_PASSWORD@db:5432/dmarq_db"
 # IMAP Settings (REQUIRED for automated report fetching)
 IMAP_SERVER="imap.example.com"
 IMAP_PORT=993
 IMAP_USERNAME="dmarc@example.com"
 IMAP_PASSWORD="STRONG_IMAP_PASSWORD"
 # CORS Origins (REQUIRED - Be specific, no wildcards)
 BACKEND_CORS_ORIGINS="https://dmarq.yourdomain.com"
 # Admin User (for initial setup)
 FIRST_SUPERUSER="admin@example.com"
 FIRST_SUPERUSER_PASSWORD="STRONG_ADMIN_PASSWORD_CHANGE_AFTER_FIRST_LOGIN"
 # Optional: Cloudflare Integration
 # CLOUDFLARE_API_TOKEN="your_cloudflare_api_token"
 # CLOUDFLARE_ZONE_ID="your_cloudflare_zone_id"
 # Security Settings (recommended)
 # SESSION_TIMEOUT=1800  # 30 minutes
 # MAX_UPLOAD_SIZE=10485760  # 10MB
 # RATE_LIMIT_PER_MINUTE=60
 ```
 ## Security Roadmap
 We are committed to improving DMARQ's security posture. Planned security enhancements:
 ### Short Term (Next Release)
 - [ ] Fix critical authentication issues on admin endpoints
 - [ ] Replace ElementTree with defusedxml
 - [ ] Add security headers middleware
 - [ ] Improve error handling to prevent information disclosure
 - [ ] Add rate limiting on sensitive endpoints
 ### Medium Term (Next 3 months)
 - [ ] Implement comprehensive input validation
 - [ ] Add automated security scanning to CI/CD
 - [ ] Enhance file upload security
 - [ ] Add audit logging for security events
 - [ ] Implement CSRF protection
 ### Long Term (Next 6 months)
 - [ ] Security audit by external firm
 - [ ] Penetration testing
 - [ ] Implement role-based access control (RBAC)
 - [ ] Add multi-factor authentication (MFA)
 - [ ] Security hardening guide
 - [ ] SOC 2 compliance documentation
 ## Security Resources
 ### Tools for Security Testing
 ```bash
 # Install security testing tools
 pip install bandit safety detect-secrets
 # Run security scans
 bandit -r backend/app -f json -o security-report.json
 safety check --json
 detect-secrets scan --baseline .secrets.baseline
 ```
 ### Recommended Reading
 - [OWASP Top 10](https://owasp.org/www-project-top-ten/)
 - [OWASP API Security Top 10](https://owasp.org/www-project-api-security/)
 - [FastAPI Security Documentation](https://fastapi.tiangolo.com/tutorial/security/)
 - [Docker Security Best Practices](https://docs.docker.com/engine/security/)
 - [NIST Cybersecurity Framework](https://www.nist.gov/cyberframework)
 ## Compliance and Standards
 DMARQ aims to comply with:
 - **GDPR**: Data privacy and protection (self-hosted approach helps with compliance)
 - **SOC 2**: Security controls (roadmap item)
 - **OWASP**: Top 10 and API Security guidelines
 - **CWE**: Common Weakness Enumeration mitigation
 ## Contact
 For security-related questions or concerns:
 - Security Email: [TODO: Add security contact email]
 - General Issues: [GitHub Issues](https://github.com/christianlouis/dmarq/issues) (non-security only)
 - Documentation: [DMARQ Docs](https://dmarq.readthedocs.io/)
 ## Acknowledgments
 We thank the security research community for helping keep DMARQ secure. Security researchers who responsibly disclose vulnerabilities will be acknowledged here (with their permission).
 ---
 **Last Updated**: 2026-02-06
 **Document Version**: 1.0
@@ -0,0 +1,72 @@
 [tool.black]
 line-length = 100
 target-version = ['py310']
 include = '\.pyi?$'
 extend-exclude = '''
 /(
  # directories
  \.eggs
  | \.git
  | \.hg
  | \.mypy_cache
  | \.tox
  | \.venv
  | venv
  | _build
  | buck-out
  | build
  | dist
 )/
 '''
 [tool.isort]
 profile = "black"
 line_length = 100
 multi_line_output = 3
 include_trailing_comma = true
 force_grid_wrap = 0
 use_parentheses = true
 ensure_newline_before_comments = true
 [tool.pytest.ini_options]
 testpaths = ["backend/app/tests"]
 python_files = ["test_*.py"]
 python_classes = ["Test*"]
 python_functions = ["test_*"]
 addopts = [
    "--verbose",
    "--strict-markers",
    "--tb=short",
 ]
 markers = [
    "slow: marks tests as slow",
    "integration: marks tests as integration tests",
    "security: marks tests as security-related",
 ]
 [tool.coverage.run]
 source = ["backend/app"]
 omit = [
    "*/tests/*",
    "*/venv/*",
    "*/__pycache__/*",
    "*/migrations/*",
 ]
 [tool.coverage.report]
 precision = 2
 show_missing = true
 skip_covered = false
 [tool.mypy]
 python_version = "3.10"
 warn_return_any = true
 warn_unused_configs = true
 disallow_untyped_defs = false
 check_untyped_defs = true
 ignore_missing_imports = true
 no_implicit_optional = true
 warn_redundant_casts = true
 warn_unused_ignores = true
 warn_no_return = true
 strict_optional = true
@@ -0,0 +1,89 @@
 [tool:pytest]
 testpaths = backend/app/tests
 python_files = test_*.py
 python_classes = Test*
 python_functions = test_*
 addopts = 
    --verbose
    --strict-markers
    --tb=short
    --cov=backend/app
    --cov-report=term-missing
    --cov-report=html
    --cov-report=xml
 markers =
    slow: marks tests as slow (deselect with '-m "not slow"')
    integration: marks tests as integration tests
    security: marks tests as security-related
 [coverage:run]
 source = backend/app
 omit = 
    */tests/*
    */venv/*
    */__pycache__/*
    */migrations/*
 [coverage:report]
 precision = 2
 show_missing = True
 skip_covered = False
 [coverage:html]
 directory = htmlcov
 [flake8]
 max-line-length = 100
 exclude = 
    .git,
    __pycache__,
    .venv,
    venv,
    build,
    dist,
    *.egg-info,
    migrations
 extend-ignore = E203, W503, E501
 per-file-ignores =
    __init__.py:F401
 max-complexity = 10
 [mypy]
 python_version = 3.10
 warn_return_any = True
 warn_unused_configs = True
 disallow_untyped_defs = False
 disallow_incomplete_defs = False
 check_untyped_defs = True
 disallow_untyped_calls = False
 disallow_any_generics = False
 ignore_missing_imports = True
 no_implicit_optional = True
 warn_redundant_casts = True
 warn_unused_ignores = True
 warn_no_return = True
 strict_optional = True
 [isort]
 profile = black
 line_length = 100
 multi_line_output = 3
 include_trailing_comma = True
 force_grid_wrap = 0
 use_parentheses = True
 ensure_newline_before_comments = True
 skip = venv,.venv,migrations
 [pylint]
 max-line-length = 100
 disable = 
    C0111,  # missing-docstring
    C0103,  # invalid-name
    R0903,  # too-few-public-methods
    R0913,  # too-many-arguments
    W0212,  # protected-access
 good-names = i,j,k,ex,_,id,db
 [bandit]
 exclude_dirs = /tests/,/venv/,.venv/
 skips = B101,B601