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