BalderComply - nLPD Compliance Scanner

Version: 2.1.0
Status: Production Ready
License: MIT

Automated Swiss Data Protection Act (nLPD) compliance auditing with 5 specialized scanners, real-time dashboard, Docker support, and comprehensive reporting.

---

🎯 Overview

BalderComply is a comprehensive compliance toolkit for auditing websites against the Swiss Federal Act on Data Protection (nLPD), which came into force on September 1, 2023. It combines automated technical scanning with detailed compliance reporting and a modern React frontend for visualizing results.

Key Features

✅ 5 Specialized Scanners:

• Cookie Scanner - Analyzes cookies and tracking consent
• Security Headers Checker - Validates HTTP security headers
• Tracker Detector - Detects third-party tracking services (15+ trackers)
• Form Analyzer - Analyzes sensitive data collection
• SSL Checker - Verifies SSL/TLS certificates

✅ Real-Time Dashboard:

• React + TypeScript frontend with Balder brand styling
• Interactive charts and visualizations (Recharts)
• Auto-refresh every 30 seconds
• Manual refresh capability
• Responsive design (mobile to desktop)

✅ Dynamic Updates:

• Auto-copy results to frontend after scans
• Cache-busting prevents stale data
• Flask API for triggering scans from UI
• Real-time progress updates

✅ Docker Support:

• Production-ready Dockerfile
• Docker Compose configuration
• CI/CD integration examples

✅ Comprehensive Reporting:

• Consolidated audit summary
• Severity-based issue categorization (CRITICAL, HIGH, MEDIUM, LOW)
• nLPD article references
• Actionable recommendations

---

🚀 Quick Start

Prerequisites

• Python 3.8+
• Node.js 16+ (for frontend)
• npm or yarn

Method 1: Standard Installation

# Clone the repository
git clone https://github.com/bastdumont/BalderComply.git
cd BalderComply

# Install Python dependencies
pip install -r requirements.txt
playwright install chromium

# Run a scan
python3 run_full_audit.py https://example.com

# Start the frontend
cd frontend
npm install
npm start
# Open http://localhost:3000

Method 2: Docker (Recommended for Production)

# Build the image
docker build -t baldercomply:2.1.0 .

# Run a scan
docker run -v $(pwd)/audit_results:/app/audit_results \
  baldercomply:2.1.0 \
  python3 run_full_audit.py https://example.com

# Or use Docker Compose
docker-compose run audit https://example.com

---

📊 Features in Detail

Scanners

1. Cookie Scanner

• Detects all cookies (first-party and third-party)
• Analyzes cookie attributes (Secure, HttpOnly, SameSite)
• Evaluates consent mechanisms
• Maps to nLPD compliance requirements
• Identifies tracking cookies

2. Security Headers Checker

• Verifies HTTP security headers
• Checks Content-Security-Policy, HSTS, X-Frame-Options
• Validates secure configurations
• References Art. 8 nLPD (data security)

3. Tracker Detector (NEW in v2.0)

• Detects 15+ tracking services:
  • Google Analytics, Facebook Pixel, LinkedIn Insight
  • Twitter, Hotjar, Mouseflow, Intercom, Drift
  • And more...
• Categorizes by type (analytics, advertising, heatmap, chat)
• Counts third-party domains and requests
• Assesses Art. 6 Abs. 6 nLPD compliance (profiling)

4. Form Analyzer (NEW in v2.0)

• Analyzes form fields for sensitive data collection
• Detects particularly sensitive data:
  • Health, religion, biometric, genetic
  • Social security numbers, financial data
• Verifies HTTPS usage for submissions
• Checks HTTP method security (GET vs POST)
• Maps to Art. 5 Abs. 3 and Art. 8 nLPD

5. SSL Checker (NEW in v2.0)

• Verifies SSL/TLS certificate validity
• Checks expiration dates
• Analyzes protocol version (TLS 1.2, TLS 1.3)
• Evaluates cipher strength
• Detects weak signature algorithms
• Identifies self-signed certificates
• References Art. 8 nLPD (data security)

Frontend Dashboard

Technology Stack:

• React 19 + TypeScript
• Tailwind CSS v3 (Balder brand colors)
• Recharts (data visualization)
• React Router v7 (client-side routing)
• Lucide React (icons)

Pages:

1. Dashboard (/) - Overview with charts and stats
2. Scanner (/scanner) - Configure and trigger scans
3. Results (/results) - Detailed issue breakdown
4. About (/about) - Information and resources

Features:

• Auto-refresh every 30 seconds
• Manual refresh button
• Cache-busting for fresh data
• Responsive design (mobile-first)
• WCAG AA accessibility compliant
• Loading states and error handling

Dynamic Updates System (NEW in v2.1)

Auto-Copy Results:

• Scan results automatically copied to frontend/public/audit_results/
• No manual intervention needed
• Runs after every run_full_audit.py execution

Cache-Busting:

• Timestamp query parameters prevent stale data
• Browser cache bypassed on every fetch
• Always displays latest scan results

API Server (Optional):

# Start Flask API server
python3 api_server.py

# API Endpoints:
# POST /api/scan - Trigger new scan
# GET /api/scan/status - Check scan progress
# GET /api/results/summary - Get audit summary
# GET /api/results/{type} - Get specific report

Frontend Integration:

• Trigger scans from UI
• Real-time progress updates
• Status polling every 2 seconds
• Auto-redirect to results when complete

---

📦 Installation

System Dependencies

macOS:

brew install python3 node

Ubuntu/Debian:

sudo apt update
sudo apt install python3 python3-pip nodejs npm

Windows:

• Download Python from python.org
• Download Node.js from nodejs.org

Python Dependencies

pip install -r requirements.txt
playwright install chromium

Dependencies:

• requests>=2.31.0 - HTTP client
• beautifulsoup4>=4.12.0 - HTML parsing
• playwright>=1.40.0 - Browser automation
• pyOpenSSL>=23.3.0 - SSL/TLS analysis
• flask>=3.0.0 - API server (optional)
• flask-cors>=4.0.0 - CORS support (optional)

Frontend Dependencies

cd frontend
npm install

Key packages:

• React 19.2.0
• TypeScript 4.9.5
• Tailwind CSS 3.4.1
• Recharts 3.4.1
• React Router DOM 7.9.5

---

🎯 Usage

Basic Scan

# Scan a website
python3 run_full_audit.py https://example.com

# Custom output directory
python3 run_full_audit.py https://example.com my_audit_results

# Results saved in audit_results/ (or custom directory)

Individual Scanners

# Cookie scanner
python3 cookie_scanner.py https://example.com output/cookies.json

# Security headers
python3 security_headers_checker.py https://example.com

# Tracker detector
python3 tracker_detector.py https://example.com

# Form analyzer
python3 form_analyzer.py https://example.com

# SSL checker
python3 ssl_checker.py https://example.com

Frontend Usage

Development Mode:

cd frontend
npm start
# Opens http://localhost:3000

Production Build:

cd frontend
npm run build
# Output in build/ directory

Deploy:

• Static hosting: Upload build/ to Netlify, Vercel, GitHub Pages
• Docker: Use nginx to serve static files
• Apache/Nginx: Copy build/ contents

API Server Usage

Start API server:

python3 api_server.py

Test API:

# Trigger scan
curl -X POST http://localhost:5000/api/scan \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

# Check status
curl http://localhost:5000/api/scan/status

# Get results
curl http://localhost:5000/api/results/summary

---

🐳 Docker Usage

Build

docker build -t baldercomply:2.1.0 .

Run Full Audit

docker run -v $(pwd)/audit_results:/app/audit_results \
  baldercomply:2.1.0 \
  python3 run_full_audit.py https://example.com

Docker Compose

# Run audit
docker-compose run audit https://example.com

# Build image
docker-compose build

CI/CD Integration

GitHub Actions Example:

- name: Build scanner
  run: docker build -t baldercomply .

- name: Run audit
  run: |
    docker run -v ${{ github.workspace }}/results:/app/audit_results \
      baldercomply python3 run_full_audit.py ${{ secrets.TARGET_URL }}

See DOCKER_GUIDE.md for comprehensive Docker documentation.

---

📊 Output Structure

audit_results/
├── audit_summary.json        # Consolidated summary
├── cookie_report.json         # Cookie analysis
├── security_headers_report.json  # Security headers
├── tracker_report.json        # Tracker detection
├── form_report.json           # Form analysis
└── ssl_report.json            # SSL/TLS verification

Audit Summary Format

{
  "audit_info": {
    "url": "https://example.com",
    "date": "2025-11-12T10:30:00",
    "version": "2.1.0"
  },
  "scanners": {
    "Cookie Scanner": "success",
    "Security Headers": "success",
    ...
  },
  "total_compliance_issues": 12,
  "critical_issues": 2,
  "high_issues": 4,
  "medium_issues": 5,
  "low_issues": 1,
  "all_issues": [
    {
      "severity": "CRITICAL",
      "description": "...",
      "nlpd_reference": "Art. 8 nLPD",
      "recommendation": "...",
      "scanner": "Cookie Scanner"
    }
  ]
}

---

🔧 Configuration

Tailwind Configuration

The frontend uses Tailwind CSS v3 with custom Balder brand styling:

Colors:

• Primary Yellow: #FFB500
• Dark Gray: #1A1A1A
• Light Gray: #E5E5E5

Custom Classes:

• .btn-primary - Solid yellow button
• .btn-secondary - Outlined button
• .card - Card component
• .badge - Severity badges
• .input-field - Form inputs

CRACO Configuration

// frontend/craco.config.js
module.exports = {
  style: {
    postcss: {
      mode: 'file', // Uses postcss.config.js
    },
  },
};

---

🐛 Troubleshooting

Issue: Dashboard Shows Old Results

Solution:

1. Click "Refresh" button in dashboard
2. Wait 30 seconds for auto-refresh
3. Hard refresh browser (Cmd+Shift+R or Ctrl+Shift+F5)
4. Run scan again: python3 run_full_audit.py https://example.com

Issue: Layout Appears Broken

Cause: Tailwind CSS v3/v4 version conflict

Solution:

cd frontend

# Check Tailwind version (should be 3.x)
npm list tailwindcss

# If v4, reinstall v3
npm uninstall tailwindcss @tailwindcss/postcss
npm install -D tailwindcss@^3.4.1
npm install
npm start

Issue: API Server Not Running

Symptoms: Scanner says "Backend Setup Required"

Solution:

# Option 1: Start API server
python3 api_server.py

# Option 2: Run manual scan
python3 run_full_audit.py https://example.com
# Then refresh frontend

Issue: Results Not Updating After CLI Scan

Solution:

# Manual copy
cd frontend
./copy-reports.sh

# Or create directory and copy manually
mkdir -p frontend/public/audit_results
cp audit_results/*.json frontend/public/audit_results/

Issue: Permission Errors During Scan

Solution:

# Check permissions
chmod +x install.sh
chmod +x frontend/copy-reports.sh

# Run with appropriate permissions
sudo python3 run_full_audit.py https://example.com

Issue: Playwright Browser Not Found

Solution:

# Reinstall Playwright browsers
playwright install chromium

# Or install all browsers
playwright install

---

📚 Documentation

Main Documentation Files

• README.md (this file) - Main project documentation
• CHANGELOG.md - Version history and changes
• NLPD_SKILL_DOCUMENTATION.md - Complete nLPD compliance methodology
• QUICK_START.md - Minimal setup guide
• EXAMPLES.md - Usage examples

Technical Documentation

• Docker: See Docker usage above
• Frontend: React + TypeScript + Tailwind CSS v3
• Backend: Python 3.8+ with Playwright
• API: Flask RESTful API (optional)

Legal & Compliance

• nLPD Official Text (FR): https://www.admin.ch/opc/fr/classified-compilation/19920153/
• nLPD Official Text (EN): https://www.fedlex.admin.ch/eli/cc/2022/491/en
• PFPDT (Swiss DPA): https://www.edoeb.admin.ch
• Geneva PPDT: https://www.ge.ch/protection-donnees

---

🛠️ Development

Project Structure

nlpd-compliance-scanner/
├── audit_results/              # Scan output (backend)
├── frontend/                   # React frontend
│   ├── public/
│   │   └── audit_results/      # Auto-copied results
│   ├── src/
│   │   ├── pages/              # React pages
│   │   ├── types/              # TypeScript types
│   │   ├── App.tsx
│   │   └── index.tsx
│   ├── craco.config.js         # CRACO config
│   ├── tailwind.config.js      # Tailwind config
│   └── package.json
├── cookie_scanner.py           # Scanner 1
├── security_headers_checker.py # Scanner 2
├── tracker_detector.py         # Scanner 3
├── form_analyzer.py            # Scanner 4
├── ssl_checker.py              # Scanner 5
├── run_full_audit.py           # Orchestrator
├── api_server.py               # Flask API (optional)
├── requirements.txt            # Python deps
├── Dockerfile                  # Docker config
├── docker-compose.yml          # Docker Compose
└── README.md                   # This file

Running Tests

# Test individual scanner
python3 cookie_scanner.py https://httpbin.org

# Test full audit
python3 run_full_audit.py https://example.com

# Test API server
python3 api_server.py
curl http://localhost:5000/api/health

# Test frontend build
cd frontend
npm run build

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

Guidelines:

• Follow existing code style
• Add tests for new features
• Update documentation
• Reference nLPD articles where applicable

---

🔐 Security & Privacy

Data Handling

• No data storage: Results saved locally only
• No external transmission: All processing local
• Privacy by design: Minimal data collection
• Secure defaults: HTTPS required, secure headers recommended

Responsible Use

This tool is for compliance auditing purposes only. Users must:

• Obtain proper authorization before scanning websites
• Respect robots.txt and terms of service
• Use results responsibly
• Consult legal professionals for compliance advice

Disclaimer: This software provides technical analysis only and does not constitute legal advice. Always consult qualified Swiss data protection lawyers for compliance matters.

---

📄 License

MIT License - See LICENSE file for details

Copyright (c) 2025 BalderComply Contributors

---

🙏 Acknowledgments

• Swiss PFPDT - For official nLPD guidance
• React Team - For excellent frontend framework
• Tailwind CSS - For utility-first CSS framework
• Playwright - For browser automation
• Open Source Community - For amazing tools and libraries

---

📞 Support & Contact

Issues & Bugs

• GitHub Issues: https://github.com/bastdumont/BalderComply/issues

Questions

• Check documentation first
• Review NLPD_SKILL_DOCUMENTATION.md for methodology
• Consult QUICK_START.md for setup help

Professional Services

For professional compliance consulting, contact Swiss data protection experts.

Official Resources

• PFPDT: info@edoeb.admin.ch, +41 58 462 43 95
• Geneva PPDT: https://www.ge.ch/protection-donnees

---

🗺️ Roadmap

v2.2 (Planned)

• WebSocket support for real-time push updates
• Scan queue management
• Historical scan comparison
• Email notifications
• Scheduled scans (cron-like)

v2.3 (Planned)

• Authentication/API keys
• Multi-user support
• Scan history database
• Advanced filtering and search

v3.0 (Future)

• AI-powered recommendations
• GDPR compliance module
• Multi-language support
• Integration with compliance platforms

---

📊 Statistics

• Scanners: 5 specialized tools
• nLPD Articles: 60+ references
• Lines of Code: 7,500+
• Documentation: 3,500+ lines
• Docker Ready: Yes
• Production Ready: Yes
• Test Coverage: Growing

---

Version: 2.1.0
Last Updated: November 12, 2025
Maintained by: BalderComply Team
Built with ❤️ in Switzerland