Writing Report Templates

Templating System

VulnScout uses Jinja2 as its templating engine, which has great community support, documentation, and supports any text-based format (AsciiDoc, HTML, Markdown, CSV, plain text, etc.).

Template Locations

Path	Purpose
src/views/templates/	Built-in templates shipped with VulnScout.
.vulnscout/templates/	Per-project host-side templates (mounted automatically if the directory exists).

Adding a Custom Template

Pass the file path directly to --report — it stages and runs the template in one step:

./vulnscout --project demo --report /path/to/my-report.adoc

Automatic Generation

Set the GENERATE_DOCUMENTS environment variable to automatically build templates at the end of every scan. Multiple templates are comma-separated (values are trimmed):

./vulnscout config GENERATE_DOCUMENTS "summary.adoc, all_assessments.adoc"

Generated files are written to the outputs directory (default: .vulnscout/outputs/). All templates can also be run on-demand from the web interface using the export button in the toolbar.

---

Global Variables Available in Templates

Variable	Type	Description
vulnerabilities	dict	All vulnerabilities found in the project, keyed by ID. Use vulnerabilities | as_list to get a list.
packages	dict	All packages found in the project, keyed by ID. Use packages | as_list to get a list.
assessments	dict	All assessments found in the project, keyed by ID. Use assessments | as_list to get a list.
author	string	Company name producing this document (from AUTHOR_NAME config).
export_date	string	Date of export as YYYY-MM-DD.
scan_date	string	Date and time of the last scan, or unknown date if unavailable.
client_name	string	Customer company name. Set via CLIENT_NAME config or overridden per-export from the web UI. May be empty.
unfiltered_vulnerabilities	dict	All vulnerabilities, bypassing any active export filter. Use | as_list to get a list. Always the full dataset.
unfiltered_assessments	dict	All assessments, bypassing any active export filter. Keyed by assessment ID.
failed_vulns	list[string]	List of vulnerability IDs that triggered the --match-condition expression. Empty when no condition was set or no vulnerability matched. Use unfiltered_vulnerabilities[vuln_id] to get the full object.
projects	dict	All projects, keyed by UUID. Use projects | as_list to get a list. Each value has the fields described in the Project Object section below.
variants	dict	All variants, keyed by UUID. Use variants | as_list to get a list. Each value has the fields described in the Variant Object section below.
scans	dict	All scans, keyed by UUID. Use scans | as_list to get a list. Each value has the fields described in the Scan Object section below.
sbom_documents	dict	All SBOM documents, keyed by UUID. Use sbom_documents | as_list to get a list. Each value has the fields described in the SBOM Document Object section below.

---

Environment Variables Available in Templates

Use env(name, default="") to access host environment variables in your templates.

For example, to fetch the value of the DISTRO environment variable:

{{ env("DISTRO") }}
{{ env("DISTRO", "unknown") }}

VulnScout will automatically scan your templates for env("...") patterns and pass the corresponding environment variable values from the host system.

When exporting, users can add filters to export only some vulnerabilities. To bypass these filters and access all vulnerabilities, use unfiltered_vulnerabilities instead of vulnerabilities and unfiltered_assessments instead of assessments. This is useful when producing a summary or showing the number of filtered-out vulnerabilities.

---

Vulnerability Object

Field	Type	Description
id	string	CVE / vulnerability ID.
found_by	list[string]	Tools that found the vulnerability (e.g. grype, yocto, spdx3).
datasource	string	Primary URL for the vulnerability.
namespace	string	Database name (e.g. nvd).
aliases	list[string]	Alternative IDs for this vulnerability.
related_vulnerabilities	list[string]	IDs of related vulnerabilities.
urls	list[string]	Additional reference URLs.
texts	dict[str, str]	Descriptions and notes. Key is the title, value is the content.
severity.severity	string	Severity level: low, medium, high, critical, unknown.
severity.min_score	float	Minimum CVSS score (0–10).
severity.max_score	float	Maximum CVSS score (0–10).
severity.cvss	list[CVSS]	List of CVSS scoring objects (version, score, vector, author).
epss.score	float	EPSS probability score (0–1).
epss.percentile	float	EPSS rank relative to all CVEs (0–1).
effort.optimistic	string	Optimistic fix time estimate in ISO 8601 duration (e.g. PT5H).
effort.likely	string	Likely fix time estimate in ISO 8601 duration (e.g. P1D).
effort.pessimistic	string	Pessimistic fix time estimate in ISO 8601 duration (e.g. P2DT4H).
packages	list[string]	Packages affected by the vulnerability, in form name@version.
published	string	CVE publish date as ISO 8601, or empty if unknown.
status	string	Current status string (see Assessment object for possible values).
simplified_status	string	Simplified status: pending, affected, fixed, or ignored.
last_assessment	Assessment	Most recent assessment object (shorthand for assessments[0]).
assessments	list[Assessment]	All assessments, sorted most recent first.
variant_ids	list[string]	UUIDs of every variant in which this vulnerability has at least one assessment.
assessments_by_variant	dict[string, list[Assessment]]	Assessments grouped by variant ID. Key is the variant UUID, value is the list of assessments for that variant.

---

Package Object

Field	Type	Description
name	string	Name of the package.
version	string	Version of the package.
cpe	list[string]	List of CPE identifiers.
purl	list[string]	List of PURL identifiers.
sbom_documents	dict[string, SBOM Document]	SBOM documents that list this package, keyed by UUID.
variants	list[string]	UUIDs of variants in which this package appears (derived from its SBOM documents).
vulnerabilities	dict[string, Vulnerability]	Vulnerabilities affecting this package, keyed by vulnerability ID.

---

Assessment Object

Field	Type	Description
id	string	Assessment ID (UUID).
vuln_id	string	ID of the vulnerability this assessment affects.
packages	list[string]	List of packages concerned.
timestamp	string	Creation datetime in ISO 8601 format.
last_update	string	Last update datetime in ISO 8601 format.
status	string	Status of the assessment (see possible values below).
simplified_status	string	Simplified status: pending, affected, fixed, or ignored.
status_notes	string	Free-text note about the status.
justification	string	Justification for the status (see possible values below).
impact_statement	string	Text explaining why the vulnerability does not apply.
responses	list[string]	List of remediation responses (see possible values below).
workaround	string	Workaround description.
workaround_timestamp	string	Datetime of this workaround in ISO 8601 format.
variant_id	string	UUID of the variant this assessment belongs to, or empty.

---

Project Object

Field	Type	Description
id	string	Project ID (UUID).
name	string	Name of the project.

---

Variant Object

Field	Type	Description
id	string	Variant ID (UUID).
name	string	Name of the variant (e.g. build configuration).
project_id	string	UUID of the project this variant belongs to.
scans	dict[string, Scan]	All scans belonging to this variant, keyed by UUID.
sbom_documents	dict[string, SBOM Document]	All SBOM documents belonging to this variant (across all its scans), keyed by UUID.
packages	dict[string, Package]	All packages found in this variant, keyed by name@version.
assessments	list[Assessment]	All assessments scoped to this variant.
vulnerabilities	dict[string, Vulnerability]	All vulnerabilities that have at least one assessment in this variant, keyed by vulnerability ID.

---

Scan Object

Field	Type	Description
id	string	Scan ID (UUID).
description	string	Description of the scan (may be empty).
timestamp	string	Scan datetime in ISO 8601 format.
variant_id	string	UUID of the variant this scan belongs to.
variant	Variant	The variant object this scan belongs to.
sbom_documents	dict[string, SBOM Document]	All SBOM documents produced by this scan, keyed by UUID.
packages	dict[string, Package]	All packages found across this scan’s SBOM documents, keyed by name@version.

---

SBOM Document Object

Field	Type	Description
id	string	SBOM document ID (UUID).
path	string	File path of the SBOM document.
source_name	string	Name of the source that produced this document.
format	string	Format of the document (e.g. spdx, cdx, openvex, yocto_cve_check).
scan_id	string	UUID of the scan this document belongs to.
variant_id	string	UUID of the variant this document belongs to (derived from its scan).
scan	Scan	The scan object this document belongs to.
packages	dict[string, Package]	All packages listed in this document, keyed by name@version.
vulnerabilities	dict[string, Vulnerability]	All vulnerabilities affecting any package in this document, keyed by vulnerability ID.

Possible values for status

Value	Description	Filter
in_triage, under_investigation	Vulnerability found but presence not confirmed. Default status.	status_pending, status_active
affected, exploitable	Vulnerability confirmed and affecting the product.	status_affected, status_active
fixed, resolved, resolved_with_pedigree	Vulnerability is fixed and no longer exploitable.	status_fixed, status_inactive
not_affected, false_positive	Vulnerability is a false positive or not affecting us.	status_ignored, status_inactive

Possible values for justification

• component_not_present

• vulnerable_code_not_present

• vulnerable_code_not_in_execute_path

• vulnerable_code_cannot_be_controlled_by_adversary

• inline_mitigations_already_exist

• code_not_present

• code_not_reachable

• requires_configuration

• requires_dependency

• requires_environment

• protected_by_compiler

• protected_at_runtime

• protected_at_perimeter

• protected_by_mitigating_control

Possible values for responses

• can_not_fix

• will_not_fix

• update

• rollback

• workaround_available

---

Filters and Helpers

In addition to Jinja built-in filters, the following custom filters are available.

Conversion

Filter	Description
as_list	Convert a dict to a list using .values().
limit(n)	Limit the number of results to n (int).
print_iso8601	Transform an ISO 8601 duration string into a human-readable format (e.g. P2DT4H → 2d 4h) or format a datetime string.

Status Filtering

Filter	Description
status(x)	Keep only vulnerabilities with status in x (str or list of str).
status_pending	Shorthand for in_triage + under_investigation.
status_affected	Shorthand for affected + exploitable.
status_fixed	Shorthand for fixed + resolved + resolved_with_pedigree.
status_ignored	Shorthand for not_affected + false_positive.
status_active	status_pending + status_affected.
status_inactive	status_fixed + status_ignored.

Score Filtering

Filter	Description
severity(x)	Keep only vulnerabilities with severity in x (str or list of str).
epss_score(x)	Keep only vulnerabilities with EPSS score ≥ x. x is a percentage in [0, 100].

Date Filtering

Both last_assessment_date and filter_by_publish_date accept date expressions in the following formats:

Format	Meaning
'>2026-01-01'	After this date (exclusive)
'>=2026-01-01'	After or on this date (inclusive)
'<2026-01-01'	Before this date (exclusive)
'<=2026-01-01'	Before or on this date (inclusive)
'2026-01-01..2026-01-31'	Between two dates (inclusive)
'2026-01-01'	Exact date match

Filter	Description
last_assessment_date(x)	Filter vulnerabilities by their last assessment date.
filter_by_publish_date(x, include_unknown=False)	Filter by CVE publish date. Pass include_unknown=True to also include vulnerabilities with no known publish date.

Note for filter_by_publish_date: Exact date match ignores time (hours, minutes, seconds). When include_unknown=True, also includes vulnerabilities without a published date.

Sorting

Filter	Description
sort_by_epss	Sort vulnerabilities by EPSS score, highest first.
sort_by_effort	Sort vulnerabilities by effort (effort.likely), most effort first.
sort_by_last_modified	Sort vulnerabilities by latest assessment date, most recent first.
sort_by_scan_date	Sort scans by timestamp, most recent first. Accepts a dict (keyed by ID) or a list.

Relational Filtering

Filter	Description
filter_by_variant(variant_id)	Keep only items that belong to the given variant. Works on assessments, scans, and vulnerabilities (matches against variant_ids). Accepts a dict or a list.
filter_by_project(project_id)	Keep only items whose project_id matches. Works on variants. Accepts a dict or a list.

---

Common Examples and Tips

Get total count of active/open vulnerabilities:

{{ vulnerabilities | as_list | status_active | length }}

Get active vulnerability with highest EPSS score:

{{ vulnerabilities | as_list | status_active | sort_by_epss | first }}

Get vulnerabilities assessed after a specific date:

{{ vulnerabilities | as_list | last_assessment_date('>2026-01-01') | length }}

Get vulnerabilities assessed in January 2026:

{{ vulnerabilities | as_list | last_assessment_date('2026-01-01..2026-01-31') }}

Get critical vulnerabilities assessed recently (after or on 2026-01-15):

{{ vulnerabilities | as_list | severity('critical') | last_assessment_date('>=2026-01-15') | sort_by_last_modified }}

List all critical unresolved vulnerabilities, sorted by most recent assessment:

{% for vuln in vulnerabilities | as_list | severity('critical') | status_active | sort_by_last_modified %}
- {{ vuln.id }} (CVSS: {{ vuln.severity.max_score }})
{% endfor %}

Use an environment variable in a template:

Product: {{ env("PRODUCT_NAME", "unknown") }}
Version: {{ env("PRODUCT_VERSION", "unknown") }}

List all projects and their variants:

{% for project in projects | as_list %}
Project: {{ project.name }}
  {% for variant in variants | filter_by_project(project.id) %}
  - Variant: {{ variant.name }}
  {% endfor %}
{% endfor %}

List most recent scans for a variant:

{% for scan in scans | filter_by_variant(variant_id) | sort_by_scan_date | limit(5) %}
- {{ scan.timestamp | print_iso8601 }}: {{ scan.description }}
{% endfor %}

List SBOM documents:

{% for doc in sbom_documents | as_list %}
- {{ doc.source_name }} ({{ doc.format }}): {{ doc.path }}
{% endfor %}

---

Traversing the data models

Every entity exposes its related entities as embedded fields, so you can traverse the data model in any direction.

The relationships are:

Project
  └─ Variant  (.scans, .sbom_documents, .packages, .vulnerabilities, .assessments)
       └─ Scan  (.sbom_documents, .packages, .variant)
            └─ SBOM Document  (.packages, .vulnerabilities, .scan)
                 └─ Package  (.sbom_documents, .variants, .vulnerabilities)
                      └─ Vulnerability  (.variant_ids, .assessments_by_variant)

Loop over vulnerabilities per variant:

{% for variant in variants | as_list %}
{{ variant.name }}
  {% for vuln in variant.vulnerabilities.values() | sort_by_epss %}
  - {{ vuln.id }} (EPSS: {{ vuln.epss.score }})
  {% endfor %}
{% endfor %}

Loop over packages per SBOM document:

{% for doc in sbom_documents | as_list %}
{{ doc.source_name }} — {{ doc.path }}
  {% for pkg_id, pkg in doc.packages.items() %}
  - {{ pkg.name }} {{ pkg.version }}
  {% endfor %}
{% endfor %}

Full traversal:

{% for project in projects | as_list %}
  {% for variant in variants | filter_by_project(project.id) %}
    {% for doc in variant.sbom_documents.values() %}
      {% for vuln in doc.vulnerabilities.values() | status_active | sort_by_epss %}
        {{ vuln.id }} in {{ doc.path }}
      {% endfor %}
    {% endfor %}
  {% endfor %}
{% endfor %}

Per-variant assessment breakdown for a single vulnerability:

{% for variant_id, assessments in vuln.assessments_by_variant.items() %}
  Variant {{ variant_id }}: {{ assessments | first | attr('status') }}
{% endfor %}

Packages that appear in multiple variants:

{% for pkg_id, pkg in packages.items() %}
  {% if pkg.variants | length > 1 %}
  {{ pkg.name }} {{ pkg.version }} appears in {{ pkg.variants | length }} variants
  {% endif %}
{% endfor %}

Most recent scan for a variant (using embedded .scans):

{% for variant in variants | as_list %}
  {% set latest = variant.scans | sort_by_scan_date | first %}
  {{ variant.name }}: last scanned {{ latest.timestamp | print_iso8601 }}
{% endfor %}