ShieldScan

AI-Assisted Web Application Vulnerability Assessment Tool for Small Businesses

ShieldScan is a practical web-based security assessment tool built for the Stellar Wave 7 program. It combines automated vulnerability scanning (OWASP ZAP or built-in scanner) with AI-generated plain-English reports and remediation guidance.

Organisation: BreachDirect · Sibling tool: RytScan (Soroban contract scanner)

📄 Product Requirements · 🏗 Architecture

• Web dashboard — enter a URL and start scanning
• Broad built-in assessment — crawls pages, checks headers, TLS, CORS, cookies, CSRF, sensitive paths, directory listing, mixed content, open redirects, SQLi/XSS on forms and URL parameters, technology fingerprinting
• OWASP ZAP integration for full DAST scanning (when Docker is running)
• Built-in scanner works without Docker — automatically used alongside ZAP or standalone
• AI-powered security reports (Claude API) with template fallback
• OWASP Top 10 category mapping
• Risk grading (A–F)
• HTML and Markdown report export
• Scan history

cd shieldscan
chmod +x start.sh
./start.sh

Open http://127.0.0.1:8000 in your browser.

sudo apt update && sudo apt install -y docker.io docker-compose
sudo systemctl start docker
sudo usermod -aG docker $USER
# Log out and back in for group change

docker compose up -d

cp .env.example .env

Edit .env:

SCANNER_MODE=zap
ZAP_API_URL=http://127.0.0.1:8081
ZAP_API_KEY=changeme
ANTHROPIC_API_KEY=sk-ant-...   # optional — uses template report if empty

./start.sh

1. Start Docker services: docker compose up -d
2. Start ShieldScan: ./start.sh
3. Open http://127.0.0.1:8000
4. Enter http://127.0.0.1:4280 (DVWA) or http://127.0.0.1:3000 (Juice Shop)
5. Check the authorisation box → Start Security Scan
6. Watch real-time progress
7. Show findings table, risk grade, and AI report
8. Export HTML report

Set in .env: SCANNER_MODE=builtin for quick testing without Docker.

shieldscan/
├── app/
│   ├── main.py              # FastAPI application
│   ├── config.py            # Settings
│   ├── models.py            # Database models
│   ├── routers/scans.py     # API endpoints
│   └── services/
│       ├── zap_client.py    # OWASP ZAP API
│       ├── builtin_scanner.py
│       ├── passive_checks.py
│       ├── scan_orchestrator.py
│       └── ai_reporter.py
├── static/                  # Web dashboard
├── docker-compose.yml       # ZAP + DVWA + Juice Shop
└── start.sh

make install-dev   # venv + prod + dev deps
make test          # pytest contract + health tests
make security-ci   # bandit + pip-audit
make ci            # lint + test + security-ci
make run           # start on :8000

Only scan systems you own or have written permission to test. DVWA and Juice Shop are deliberately vulnerable lab apps for education.

Michael Victory Osisienimo — BreachDirect