# Project plan — vulnerability_scan

Evidence date: 2026-09-29.

Source repository: `git@bitbucket.org:overdrive/vulnerability_scan.git`.

Inspected revision: `main` at `de29c65` (2025-04-02, joshgatdew, "Latest"). The scan-host path `~/projects/sonar_scan/repos/vulnerability_scan` was not on this machine. The tree below was read from that git revision. Credential values are omitted.

This plan describes what the repository contains. It does not decide what the product should become.

## Product

The repository README titles the product **GVM Scanner CLI Application**. It is a Python command-line tool that talks to a Greenbone Vulnerability Management (GVM) instance, runs or reuses a vulnerability scan of one or more named targets, builds an HTML report, and can email that report through Microsoft 365. An optional flag writes the same HTML into a Supabase table.

Provenance: **Documented** in `readme.md`. The behaviour is **Implemented** in `cli_app/cli.py`.

There is no separate product requirements document in the source repository or in Silicon Ark before this set.

The Greenbone stack itself is not written here. `green_bone_docker/docker-compose.yml` runs Greenbone Community Edition containers and builds the CLI image next to them.

## Branch reality

| Line | Tip | Date | What it is |
|---|---|---|---|
| `main` (default; `origin/HEAD`) | `de29c65` | 2025-04-02 | Only branch. 17 commits from 2025-02-26 to 2025-04-02 |

No other local or remote branches were present at inspection.

History falls into two stretches:

- 2025-02-26 — Jaco Brits added `.gitignore`, `sonar-project.properties`, and `bitbucket-pipelines.yml` through Bitbucket's online editor.
- 2025-02-28 to 2025-04-02 — joshgatdew (`joshua@overdrive.co.za`) added the CLI, the Greenbone compose file, the README, Microsoft 365 mail, HTML reports, Docker packaging, and socket-permission fixes.

The last commit, `de29c65`, changes only the `cli-app` service `depends_on` conditions in `green_bone_docker/docker-compose.yml`.

**Discrepancy:** the task-creation scan listed `sonarqube_scan.bat` at the repository root. That file is not in git history. Provenance: **Unknown** — it may have been an untracked file on the scan host.

## Objectives (inferred from the implementation and the README, not from a written plan)

- Give an operator a repeatable way to start the Greenbone Community Edition stack with a gvmd socket exposed on the host.
- Create a Greenbone target and task for a hostname the first time it is seen, then reuse them.
- Run the scan, or attach to one that is already running, or skip the scan and load the last report.
- Turn the XML report into an HTML document grouped by severity and send it to a colon-separated list of mailboxes.
- Optionally store that HTML in Supabase.

## Scope

### In scope of `main`

1. Python CLI at `cli_app/cli.py`, with a virtualenv installer and pinned `requirements.txt`.
2. A Debian-based image (`cli_app/Dockerfile`, `cli_app/entrypoint.sh`) that runs the CLI as user `gvm`.
3. Greenbone Community Edition compose project `greenbone-community-edition` and the shell wrappers under `green_bone_docker/`.
4. Operator documentation in `readme.md`, plus two screenshots under `documentation/` of a Stack Overflow answer about Office 365 OAuth.
5. A captured Greenbone XML-as-JSON report at `cli_app/test.json`. The CLI does not read this file.
6. Bitbucket Pipelines SonarQube scan on `main`, and `sonar-project.properties`.

### Out of scope / not in this repository

- The Greenbone feed contents, scanner engine, and web UI source. Those come from `registry.community.greenbone.net` images.
- A scheduler. The README says a `.env` file allows cron, but no cron unit or timer is in git.
- A reader for the Supabase table `scan_que`. This repository only inserts a row.
- Automated tests. No test runner, no pipeline test step, and `test.json` is not referenced by `cli.py`.
- A written backlog, release process, or statement of which hosts are in the production scan list.

## System architecture

```text
Operator
   |  python3 cli.py <targets> [options]
   |  or green_bone_docker/cli_app.sh <targets> [options]
   v
cli_app (Python, python-gvm GMP)
   |  Unix socket (active path)
   |  SSH and TLS connection helpers exist; the running path does not call them
   v
gvmd  (Greenbone Community Edition container)
   |-- PostgreSQL (pg-gvm)
   |-- ospd-openvas / openvas / openvasd / redis / feed volumes
   |-- GSA web UI published on 127.0.0.1:9392
   |
   +-- HTML report
         |-- Microsoft 365 via O365 (when --mail is set)
         +-- Supabase table scan_que (when --supabase is set)
```

SonarQube is a Bitbucket Pipeline on `main`. It does not deploy the CLI or the compose stack.

## Major components

| Component | Role | Evidence |
|---|---|---|
| `cli_app/cli.py` | Argument parsing, GMP session, target/task setup, scan wait, HTML, mail, Supabase | Single script, about 960 lines |
| `green_bone_docker/docker-compose.yml` | Greenbone Community Edition plus a `cli-app` service built from `../cli_app` | Compose project name `greenbone-community-edition` |
| `green_bone_docker/*.sh` | Install, start, stop, logs, gvm-tools shell, one-shot CLI container | README install section |
| `readme.md` | Install, usage, `.env` key names, socket note | Operator-facing |
| `bitbucket-pipelines.yml` | SonarQube on branch `main` | No other steps |

## Milestones

No milestone plan is written in the repository. The commits are the only timeline:

| Date | Commit | What landed |
|---|---|---|
| 2025-02-26 | `8530ed3`, `62e5873`, `9b7a548` | Repository shell, Sonar properties, pipeline |
| 2025-02-28 | `f1599e4` | CLI, requirements, compose file, management scripts |
| 2025-03-05 to 2025-03-07 | `b31ac12`, `29a49d7`, `afadd84` | HTML report, mail, then Microsoft 365 mail, screenshots, `test.json` |
| 2025-03-11 to 2025-03-14 | `202010d`, `d4f89d2`, `092cdc4`, `5515fcb` | README, TLS/SSH helpers, argv splitting, multiple targets |
| 2025-03-16 to 2025-03-18 | `06d81ec`, `a2f4f0c` | Zero-host handling, report grouping |
| 2025-03-25 to 2025-04-02 | `f5d71af`, `f9b1840`, `d32a02c`, `de29c65` | CLI image, socket path and permissions, compose `depends_on` |

Nothing in git is dated after 2025-04-02. Whether anyone still operates this stack is **Unknown / Requires Confirmation**.

## Known dependencies

- Python 3 and `python-venv` for a host install (`readme.md`). The image uses Debian `stable-slim` and its `python3`. The minor version inside that image was not built during this inspection.
- Docker Engine and the Compose plugin, documented for Ubuntu.
- Greenbone Community images and feed release `24.10` for the data-sync services.
- A GVM user (`USERN` / `PASS` in `.env`, or an interactive prompt).
- For mail: an Azure app registration (`ms_tenant_id`, `ms_app_id`, `ms_app_secret_val`) and a token file `o365_token.txt`.
- For `--supabase`: `SUPABASE_URL` and `SUPABASE_KEY`, and a table named `scan_que`. The insert path as written does not pass the key correctly. See the PRD and technical documentation.
- SonarQube: pipeline variables `SONAR_HOST_URL` and `SONAR_TOKEN`. Project key `overdrive_vulnerability_scan_491f4e22-35d3-4703-8862-c62d23d68958`.

## Current project status

**Implemented** and present on `main`: CLI scan flow, HTML report, Microsoft 365 send, Docker image, Greenbone compose recipe, SonarQube pipeline.

**Not active in the running script:** generic SMTP (`send_email` and the `mail_*` loader are commented out), writing `scan_results.html`, and the SSH call site.

**No automated test suite** and **no deploy step** in the pipeline.

**Human review:**

- Confirm whether `sonarqube_scan.bat` should exist. It is not in git.
- Confirm whether the Supabase insert is expected to work. The code overwrites the URL variable with the key and then passes that one variable as both client arguments.
- Confirm whether `docker compose up` is expected to start the `cli-app` service. That service waits for `gvmd` to complete successfully, and `gvmd` is a long-running container.
- Confirm the live Greenbone version. The compose file pins feed release `24.10` and image tag `stable`. The committed sample report records GMP `22.6`.