VigilentOps

VigilentOps (called SecureGuard in several service names) is a self-hosted security scanning lab. Gitea stores the target repository, Jenkins runs scanners, a FastAPI service stores findings in PostgreSQL, and a Celery worker can propose Python fixes as draft pull requests. People must review and test those proposals before merging them.

This is a lab reference implementation. Docker Compose publishes one HTTPS gateway on port 3000; Gitea, the findings dashboard, Jenkins, Grafana and Prometheus use routes through it. See Gateway setup for TLS, login, service paths and migration. AI-generated code needs review and validation before it can be accepted as remediation. For the current completion status, known blockers, and next actions, see the project checklist and latest server acceptance record.

How it works

flowchart LR
    G[Gitea push] --> J[Jenkins pipeline]
    J --> S[Security scanners]
    S --> A[Orchestrator API]
    A --> P[(PostgreSQL: scans and findings)]
    A --> C[CVE enrichment worker]
    A --> R[Redis / Celery AI worker]
    R --> D[Draft Gitea pull request]
    P --> U[React dashboard]
    A --> M[Prometheus / Grafana]
    D --> H[Human review and branch validation]

Loading

1. A Gitea push to main, develop, or master triggers the Jenkins Generic Webhook Trigger job.
2. Jenkins checks out the pushed repository, verifies its commit, registers the target and shared pipeline commits, and runs scanners. Required output and uploads must pass validation. The API records report receipts and refuses completion with missing required reports. Zero findings and explicit OSV/Hadolint/ShellCheck not-applicable coverage remain distinguishable.
3. The orchestrator parses supported SARIF reports and Bandit JSON into findings. Dockle image-configuration results now use SARIF; Syft's SPDX SBOM is inventory only. The CVE service queues enrichment separately.
4. The AI worker considers open, medium or higher Python SAST findings. It checks syntax, change size and existing Python interfaces. Bandit candidates must reproduce the original rules and remove them without adding medium/high results, ignoring suppression comments. Accepted candidates become a WIP: PR against the scanned branch, with all stored findings across all tools in numbered comments. Secret-bearing details are omitted. Runtime correctness still requires review and server checks.
5. A reviewer checks the diff against the original finding, runs relevant checks on the PR branch, and merges only after approval. The Jenkins build on the base branch does not validate a later AI PR.

See Architecture for the service map, repository layout, and API flow. See AI pull request review for the review procedure and Operations for backup and response planning.

The lab has native Jenkins accounts/permissions, private hooks, report receipts, live Falco capture and a dashboard built with Vite/Node 24. The dashboard polls scan summaries and pages finding records. All 13 target repositories have completed scans using shared pipeline 83b5434 (builds #379–391); later changed heads have separate scan evidence. Jenkins now uses the pinned 2.580.1 LTS / Java 25 image and 97 managed plugin pins. The latest free-model policy passed 99 Python tests on Kali; eight monitoring targets and 22 Grafana queries passed. See deployment procedure for subsequent updates. CHECKLIST.md tracks finding dispositions, broader recovery workflows and final release acceptance; the lab is not yet complete.

The AI model pool now permits only seven approved OpenRouter :free variants, with zero-price constraints, bounded attempts and route cooldowns. Earlier direct-provider compatibility checks do not validate these new routes. One SQL fix was manually corrected, reviewed and rescanned before merging; this does not establish that models can repair every finding. See Jenkins upgrades for plugin maintenance and recovery.

Repository map

Path	Purpose
ai-engine/	FastAPI orchestrator, report parsers, database migrations, Celery AI worker, notifications
cve-intel/	CVE enrichment API and worker
jenkins/pipelines/	Jenkins scanner pipeline
scanners/	Shared Semgrep rules and Dockerfile lint policy
dashboard/	React UI served by Nginx; /api proxies to the orchestrator
monitoring/	Prometheus, Grafana, Falco, Wazuh, Loki, and Promtail configuration
wazuh-proxy/	Internal Wazuh API proxy used by Grafana
proxy/	HTTPS gateway; the only published application port
scripts/	Setup, coverage audits, private triage, backups and server acceptance tools
tests/	Python tests for parsing, API import, and remediation safeguards
docs/	Deployment, architecture, validation, and review guides

Run on the lab server

Use a Linux host with Docker Engine and Compose v2. Configuration and startup steps are in Deployment. Copy .env.example to .env, replace placeholders, and prepare the private TLS and gateway login using python3 scripts/configure_gateway.py --public-url https://SERVER-IP:3000. The base stack starts with docker compose up -d --build; Jenkins and monitoring use the ci and monitoring profiles.

This project's working workflow is to edit and push from the development checkout, pull the branch on the lab server, and run builds and tests on the lab server. See Testing for server commands. Changes tested only on main do not validate an AI PR branch.

Scope and limitations

The Jenkinsfile includes Semgrep, Bandit, Gitleaks, Trivy, Checkov, Snyk when configured, Dockle, OWASP Dependency-Check, Grype, OSV-Scanner, Syft, Hadolint, and ShellCheck stages. See Scanner coverage for scope, required reports and limitations. Their availability and output depend on the server, scanner images, credentials, and target repository. The implemented pipeline does not provide DAST, malware scanning, artifact signing, or an automatic merge gate. Runtime monitoring is available through the optional monitoring profile.

Model calls may send source files and finding details to the configured provider. Read Deployment before enabling AI remediation or exposing services.