AG GitHub Security Scanner

AG GitHub Security Scanner is a local-first security scanning dashboard for authorized testing. It provides scoped scan workflows, real-time WebSocket telemetry, SQLite audit trails, modular scanner engines, and local heuristic vulnerability analysis without sending scan data to a third-party service.

Use this project only on systems you own or have explicit written permission to test.

Highlights

• Express and WebSocket backend with Helmet, CORS, and rate limiting.
• SQLite database in WAL mode for local persistence.
• JWT authentication with admin, operator, and viewer roles.
• Scanner modules for headers, TLS, ports, OSINT DNS, web checks, API discovery, and common path discovery.
• Optional nmap integration with a pure Node.js TCP fallback.
• OWASP Top 10 mapping, CVSS-style scoring, attack-chain hints, and remediation guidance.
• Live dashboard with scan console, reports, team settings, and exportable HTML/JSON reports.

Legal And Ethical Scope

The app requires users to confirm authorization before a scan is queued. Scan creation, stop requests, authentication events, registration, and team changes are written to the audit log.

Do not use this project for unauthorized scanning, intrusion, exploitation, credential theft, evasion, persistence, or activity that violates laws, contracts, or platform terms.

Quick Start

npm install
cp .env.example .env
npm run dev

Open http://localhost:3000, register a workspace, and create an authorized scan.

On Windows PowerShell, copy the example environment file with:

Copy-Item .env.example .env

Configuration

PORT=3000
JWT_SECRET=change-me-to-a-long-random-secret
DATABASE_PATH=database/ag-security-scanner.sqlite
MAX_CONCURRENT_SCANS=2
SCAN_SOCKET_TIMEOUT_MS=900
SCAN_FETCH_TIMEOUT_MS=6000
ALLOW_LOCAL_TARGETS=true
ENABLE_NMAP=true

Set ENABLE_NMAP=false to force the Node.js scanner. If nmap is enabled but unavailable, the app falls back to the Node.js TCP connect scanner.

Roles

• admin: manage team members and scans.
• operator: launch and stop scans.
• viewer: view dashboards and reports.

API Overview

• POST /api/auth/register
• POST /api/auth/login
• GET /api/auth/me
• POST /api/scans
• GET /api/scans
• GET /api/scans/:id
• POST /api/scans/:id/stop
• GET /api/scans/:id/report
• GET /api/dashboard/stats
• GET /api/teams/members

Verification

npm run check
npm start

Project Structure

ai/          Analysis and report generation
config/      Database and app constants
database/    SQLite schema
lib/         Queue, validation, logging, and payload data
middleware/  Authentication middleware
public/      Browser dashboard
routes/      HTTP API routes
scanners/    Modular scanner engines
scripts/     Local verification scripts

Responsible Disclosure

If you discover a vulnerability in this project, please follow SECURITY.md. Do not open a public issue for sensitive reports.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before opening an issue or pull request.

License

Released under the MIT License.