# report_generator

Builds the PDF report of one stored scan, from the artifacts that scan put in the bucket.

## Installing

The package lives in `report_generator/`, beside the `pyproject.toml` that builds it. Install it
from the repository root — the directory holding this file, not the package directory:

```
pip install -e .            # add [dev] for the test and lint tooling
```

Installing from inside `report_generator/` does not work: `packages.find` looks for the package as a
subdirectory, so it finds nothing, and the `report_generator` console script is then installed
pointing at a module that was never put on the path.

## Running

```
report_generator --scan_id <uuid> [--path <file-or-directory>] --config config.json
```

Without `--path` the report is written into `reports/`. The S3 secret comes from the environment:
`PERSISTENT_STORAGE_STORAGE_CONFIG_S3_SECRET_ACCESS_KEY` (and the database password from
`PERSISTENT_STORAGE_STORAGE_CONFIG_DATABASE_PASSWORD`). The name is not this tool's to choose: it is
derived from the config path `inject_secrets` fills in under — `persistent_storage.storage_config` —
by the one naming convention in `cc_common.config.env_var_name`, so it stays whatever the monorepo
calls it. A `.env` beside the `pyproject.toml` is read too. `--config` is resolved relative to the
working directory.

## How it is put together

Four steps, each its own module, so that the one that will change is the one that is separate:

| Module | Does |
| --- | --- |
| `report_generator/sources.py` | Reads the scan and its files out of the store. **The only module that knows which store.** |
| `report_generator/rendering.py` | Decides which stored file feeds which part of the report, and parses it. |
| `report_generator/context.py` | Maps the parsed artifacts onto the page, and writes `<xxx>` where they say nothing. |
| `report_generator/layout.py` | Draws `template/report.html.j2` through WeasyPrint. |

No parsing of its own. SARIF and the vulnerability report are read by the summarisers in
`cipherverifier.core.services`, which are written to be free of Django and of any store; the CVSS
vectors by `persistent_storage.utils.cvss_utils`.

### What it cannot fill in

A field the artifacts do not answer is written as `<xxx>`, never guessed or quietly dropped. Today
that is the report and artifact ids, the manufacturer, the analysed lines of code, the language
breakdown, and the tools and profile of each pipeline stage — the metadata records that a stage ran
and how long it took, not what it ran.

A measured zero survives: `0 filtered` is a reading, and a blank is a gap.

## Moving it to archon

`sources.collect()` is the whole of it. It returns files by name and the rows a report lists;
everything after that point works on bytes and cannot tell which store handed them over. Pointing it
at archon's tables is a change to that function and to nothing else.

## Its relationship to the monorepo

This repository is the split of `src/persistent_storage/report_generator/` out of the monorepo. The
package names nothing about itself — every import inside it is relative — so the split was a move
and not a rewrite: the sources sit unchanged under `report_generator/`, with `pyproject.toml` beside
them rather than inside them.

`report_generator/vendor/` supplies everything the package borrows from the monorepo — `cc_common`,
`persistent_storage.shared`, and the two summarisers. `vendor/__init__.py` puts the copies on the
path when the real packages are not installed, and stays out of the way when they are, so the same
sources run in both places. See `report_generator/vendor/README.md`.

Still to come across: `tests/persistent_storage/test_report_*.py` from the monorepo, with
`persistent_storage.report_generator` changed to `report_generator` in their imports. Until they
land, `testpaths = ["tests"]` in `pyproject.toml` points at a directory that does not exist yet.

On the monorepo side, `tests/persistent_storage/test_report_vendor.py` performs this same split into
a temporary directory on every run and renders a report from it, so the copies cannot quietly stop
being sufficient.

### Native dependencies

WeasyPrint needs Pango and cairo, which pip does not install:

```
brew install pango          # macOS
apt-get install libpango-1.0-0 libpangoft2-1.0-0    # Debian/Ubuntu
```