ZAP OWASP Web Interface
One-click deploy on Railway!

About this boilerplate

This repository provides a lightweight Node.js application with a modern web interface for interacting with the ZAPROXY API. Simply launch the app, enter the URL of the website you want to scan for vulnerabilities, and click the Start Scan button. Once the scan is complete, you can view the results directly in the web interface or download a detailed PDF report.

⚠️ Important Memory Requirements:

• The ZAP service requires at least 2GB of RAM to function properly, especially for scanning larger sites
• Railway's free tier (500MB) is not sufficient for most scans
• For production use, consider upgrading to Railway's Hobby or Pro plan
• Memory usage increases with site complexity and depth of scanning

Regular OWASP scans are essential for maintaining robust web security, especially for organizations aiming to comply with standards like ISO27001 or similar certifications.

Why run in the cloud?

This cloud-based setup allows you to perform OWASP scans effortlessly without needing to download or install any software. It is particularly beneficial for users operating in environments with strict security policies that restrict installing third-party software, such as ZAP. By running in the cloud, you gain convenience, and compliance with organizational security requirements.

No-code Cloud Setup

Use one-click deploy template:

This template automatically launches the required ZAP docker container, then builds the web interface and connect it to the API, so you don't have to do anything. But, note that the ZAP service is memory-intensive - ensure your deployment environment has sufficient resources (minimum 2GB RAM) for reliable scanning, but for larger scans more memory might be required.

Local Setup

1. Clone the project: Launch on Railway and eject watch how. Alternatively, clone this repo or fork it.
2. Install dependencies:
   • pnpm install
3. Rename .env.template to .env (edit if needed)
4. Start everything with one command:
   • pnpm local

pnpm local will:

• start or create a local zaproxy/zap-stable:latest Docker container
• build the app and run the existing server
• stop the local ZAP container again when you stop the command

Optional helper commands:

• pnpm zap:start to start only the ZAP container
• pnpm zap:stop to stop only the ZAP container

System Requirements

• Memory: Minimum 2GB RAM for the ZAP service
• Platform: Any system capable of running Docker containers
• Network: Stable internet connection for scanning external sites

Preconfigured Features & Integrations

• Simple React frontend with Mantine UI components
• Two-phase security scanning:
  • Spider scan to map the application
  • Active scan to find vulnerabilities
• Real-time scan progress monitoring
• PDF report generation with:
  • Summary of findings
  • Detailed vulnerability descriptions
  • Solutions and references
  • Risk-based categorization
• Optional PostgreSQL database integration:
  • Automatic scan persistence when database is available
  • Fallback to in-memory storage when no database is configured
  • Completed scans are stored in the database and cleared from memory
• Railway-ready configuration

Requirements

• Node.js >= v18.0.0
• pnpm >= v8.0.0
• A running ZAP OWASP Docker instance

Commands

• pnpm local to automate the original local flow: start Docker ZAP, build, and run the app.
• cd frontend && pnpm dev to start the React frontend only.
• cd backend && pnpm dev to start the Node.js backend only.
• pnpm build && pnpm start to compile and run from compiled source.

Demo sites to scan

• https://google-gruyere.appspot.com/start for a quick scan
• https://juice-shop.herokuapp.com/ for a longer deeper scan

Project Structure

The project is organized as a monorepo containing both frontend and backend:

/
├── frontend/ # React frontend application
├── backend/ # Node.js/Express backend service
└── package.json # Root package.json for workspace management

Features

• Clean and intuitive user interface.
• Download PDF report of scan result.
• Backend proxy to ZAP service.
• Optional database persistence for scan results.
• Scan scheduling system:
  • Schedule scans to run at specific times
  • Configure repeat patterns (daily, weekly, monthly)
  • Automatic execution of scheduled scans
  • Real-time monitoring of scheduled scan status

Database Integration

The application supports optional PostgreSQL database integration:

• Flexible Operation: Works seamlessly with or without a database connection
• Railway Integration: When deployed on Railway, the database is automatically configured
• Local Development: For local development, you can:
  • Run without a database (scans stored in memory only)
  • Connect to a local PostgreSQL instance
  • Connect to a remote PostgreSQL database

Prisma ORM

This project uses Prisma ORM for database operations:

• Automatic Client Generation: The Prisma client is automatically generated during the build process
• Schema-First Approach: The database schema is defined in backend/prisma/schema.prisma
• Type Safety: Prisma provides type-safe database access with TypeScript integration

Configuring Database Connection

To enable database persistence, set the DATABASE_URL environment variable in your .env file:

DATABASE_URL=postgresql://username:password@localhost:5432/zapscans

When the application starts:

1. It checks for a valid DATABASE_URL environment variable
2. If found, it establishes a connection to the database
3. If not found or connection fails, it continues to operate using in-memory storage

Benefits of Database Persistence

• Long-term Storage: Scan results persist across application restarts
• Memory Efficiency: Completed scans are removed from memory after being stored in the database
• Historical Data: Access to historical scan results even after server restarts

API Endpoints

Backend

Start a new scan:

POST /api/v1/scans

Request:

{
  "url": "https://example.com"
}

Response:

{
  "uuid": "...",
  "status": "started",
  "url": "https://example.com"
}

Get scan status and results:

GET /api/v1/scans/:uuid

Response:

{
  "uuid": "...",
  "status": number, // 0 for spider scanning, 1-100 for active scanning progress
  "isComplete": boolean,
  "results": [
    {
      "name": "...",
      "risk": "High|Medium|Low|Informational",
      "description": "...",
      "solution": "...",
      "reference": "...",
      "url": "..."
    }
  ],
  "error": {  // Only present if there's an error
    "message": "...",
    "code": "...",
    "details": "..."
  }
}

Generate PDF report:

POST /api/v1/reports/generate

Request:

{
  "uuid": "..." // UUID of the scan
}

Response: Binary PDF file with proper Content-Disposition header for download.

A template by,