SecuScan

Local-first security scanning for learning, experimentation, and ethical pentesting workflows.

Project Purpose

SecuScan is an open source, plugin-driven platform for running security scans from your own machine. It combines a FastAPI backend, a React frontend, and a growing plugin system for recon, web, cloud, container, and reporting workflows.

The project is designed to be:

• Local-first: scan data stays on infrastructure you control.
• Contributor-friendly: frontend, backend, plugins, and docs all have clear entry points.
• Safety-aware: the product is built around ethical and learning-oriented usage.

Who It Is For

• Students and GSSoC contributors who want a real-world full-stack open source security project.
• Security learners who want a UI-backed toolkit instead of only raw CLI flows.
• Developers and researchers who want to extend scanners, parsers, reports, or workflow automation.

Core Areas

• Scan orchestration and API flows in backend/secuscan
• React UI and dashboard experience in frontend/src
• Plugin metadata and parser integrations in plugins
• Reports, exports, and result normalization across backend and frontend

Repository Map

• backend/: FastAPI app, execution logic, database/config, plugin loading, workflows
• frontend/: React + Vite app, routes, pages, shared components, and test config
• plugins/: scanner metadata, parser code, and plugin-specific helpers
• testing/backend/: Python unit and integration tests plus backend test scripts
• frontend/testing/: frontend unit and end-to-end test files
• docs/: supporting project documentation
• scripts/: helper scripts for signing, benchmarking, and maintenance

Prerequisites

For a fresh local setup, make sure your machine has:

• python3 3.11 or newer
• Node.js 20 or newer
• npm 10 or newer
• Docker Desktop or Docker Engine if you want the Compose workflow

If your machine has multiple Python versions installed, ./setup.sh now looks for a compatible python3 automatically. You can also force one explicitly with PYTHON=/path/to/python3.11 ./setup.sh.

The scripted local setup path was re-checked from a fresh clone with a compatible Python 3.11+ interpreter.

Quick Start

Choose one local development path.

Option 1: Simple Local Dev

This is the fastest way to get the app running for UI or backend contributions from a fresh clone.

git clone https://github.com/utksh1/SecuScan.git
cd SecuScan
chmod +x setup.sh start.sh
./setup.sh
./start.sh

After startup:

• Frontend: http://127.0.0.1:5173
• Backend API: http://127.0.0.1:8000
• Swagger docs: http://127.0.0.1:8000/docs

Option 2: Docker Compose Stack

Use this if you want the containerized app stack with Postgres and Redis.

git clone https://github.com/utksh1/SecuScan.git
cd SecuScan
docker compose up --build

After startup:

• Frontend: http://127.0.0.1:5173
• Backend API: http://127.0.0.1:8081

Manual Development Commands

Backend

Python version: python3 in these commands must resolve to 3.11 or newer. If your system default is older, substitute the full path (e.g. python3.11, python3.12) or use PYTHON=/path/to/python3.11 ./setup.sh instead. Run python3 --version to check.

cp .env.example .env
python3 -m venv venv
source venv/bin/activate
pip install -r backend/requirements.txt
pip install -r backend/requirements-dev.txt
python3 -m uvicorn backend.secuscan.main:app --reload --host 127.0.0.1 --port 8000

Frontend

cd frontend
npm install
npm run dev -- --host 127.0.0.1 --port 5173

Running Tests

Backend tests

./testing/test_python.sh

Frontend tests

cd frontend
npm run test

Frontend end-to-end tests

cd frontend
npm run e2e

New Contributors Start Here

If this is your first contribution, start with one of these areas:

• Docs: improve setup steps, fix outdated instructions, or clarify contributor guidance.
• Frontend polish: small UI fixes, loading states, empty states, and test coverage.
• Backend cleanup: validation, API consistency, workflow edge cases, and unit tests.
• Plugins: metadata fixes, parser improvements, and result normalization.

Good first places to read before coding:

• Contribution Guide
• Code of Conduct
• Security Policy
• Plugin Catalogue
• Product Specification

Contribution Guidelines

Before opening a pull request:

1. Fork the repo and branch from main.
2. Pick an issue or discuss the change before starting large work.
3. Keep pull requests scoped and include tests when behavior changes.
4. Update docs if you change setup, APIs, workflows, or contributor-facing behavior.

Detailed contributor expectations live in CONTRIBUTING.md.

Detailed Documentation

Long-form product and planning material lives outside the main README so onboarding stays readable:

• SecuScan Product Specification
• Plugin Catalogue

Tech Stack

• Backend: FastAPI, Pydantic, Uvicorn, SQLite/Postgres, Redis
• Frontend: React 18, TypeScript, Vite, Vitest, Playwright
• Plugins: metadata-driven scanner integrations and parser modules

Contact

For questions, contributor coordination, onboarding help, or setup issues, use GitHub Issues.

For responsible disclosure of security issues, follow the private reporting guidance in SECURITY.md.

Responsible Use

SecuScan is intended for authorized security testing, education, and research. Do not use it against systems you do not own or explicitly have permission to assess.

License

This project is released under the MIT License.

Licensing Notes

• LICENSE is the canonical legal text for this repository.
• Contributions merged into this repository are distributed under the same MIT License unless explicitly stated otherwise.
• Third-party tools, libraries, and external scanners referenced by SecuScan may have their own licenses and usage terms. Check upstream projects before redistributing bundled integrations.