Making Container Reports Durable: Audit-Ready Data Using the Qualys API

As part of its ongoing platform improvements, Qualys is simplifying container data retention, to help customers maintain faster, more efficient environments. Beginning October 2025, the maximum retention period for container records will change from 13 months to 30 days. The update reduces data clutter, improves performance, and ensures teams always have access to the most relevant runtime information.

For teams that require long-term visibility, whether for audits, compliance validation, or historical analysis, Qualys provides a flexible path forward. Using the Qualys Container List API, teams can automatically back up container inventory and vulnerability data, preserving a durable, audit-ready history outside the platform.

Why This Script Matters

As container environments grow in size and complexity, retaining historical visibility becomes as important as monitoring current risks. The new retention model helps streamline active data within the Qualys platform; however, many customers still require long-term access to historical container information for audits, compliance validation, and internal investigations.

To address this need, this Python-based automation script uses the Qualys Container Security API (/csapi/v1.3/containers/list) to continuously extract, store, and index container inventory and vulnerability data. By maintaining a local, durable copy of this information, teams can create their own long-term audit trail, perform retrospective analysis, and meet compliance requirements even after the platform’s retention window expires.

How It Works

The script connects to the Qualys Container Security API and retrieves container data for configurable date ranges, typically processed week by week to keep exports manageable and repeatable. Each run is idempotent, meaning it can safely resume or re-run without duplicating data, ensuring complete and consistent coverage over time.

The export process follows a two-pass design:

• Pass 1 captures raw API output in structured JSON files, preserving every attribute for long-term reference.
• Pass 2 transforms that data into flattened, analysis-ready tables (CSV or JSON), where users can define which columns to include.

By combining QQL-based filtering for targeted subsets and custom column selection for tailored reports, the script offers a flexible, automated way to maintain an audit-ready container history, even as platform retention windows evolve.

Key Benefits

• Preserve container inventory and vulnerability data beyond the new 30-day retention window.
• Generate dual-format archives (JSON for completeness, CSV for analysis) for maximum flexibility and portability.
• Maintain detailed, per-container vulnerability visibility to support audits, forensics, and compliance reviews.
• Automate weekly exports to ensure continuous, hands-free data capture and compliance tracking.
• Customize reports with QQL filters and selectable CSV fields to meet specific reporting or regulatory needs.

Practical Use Case

Security and compliance teams preparing for quarterly or annual audits often need to demonstrate the vulnerability state of containers that existed months earlier. With this script, they can automate weekly exports to build a durable, off-platform archive of container inventory and vulnerability data. This ensures that even as retention limits evolve, teams maintain continuous access to historical evidence required for audits, investigations, and compliance validation.

Setup & Execution Steps

Follow the steps below to clone, configure, and run the script.

1. Clone the Repository

Use the following command to clone the GitHub repository containing the script:
git clone https://github.com/Qualys/cs-container-reports

Then, navigate into the script directory:
cd cs-container-reports

2. Set Up Environment Variables

Before running the script, export your Qualys Access Token using:
export QUALYS_TOKEN="your_qualys_access_token_here"

The script uses environment variables only for authentication and configuration — no hardcoded fallback tokens.

3. Run the Script

Example command to run the script with filters, custom columns, and date range:

python3 weeklycontainerreport.py https://gateway.qg2.apps.qualys.com \ 
  --optional_filter "state:RUNNING and imageId:d1a50f311f32" \ 
  --csv_columns "containerId,uuid,name,state,vuln_qid,vuln_software_names" \ 
  --start_date 2025-10-21 --end_date 2025-10-27

Usage Example

To fetch and store your container inventory and vulnerability data, use:
 
python3 weeklycontainerreport.py
https://gateway.qg2.apps.qualys.com --start_date 2025-09-27 --end_date 2025-10-04

Replace the Gateway URL with your platform’s API endpoint. The script will authenticate via your Qualys API token, fetch data, and generate JSON and CSV reports under `weekly_reports/` and `weekly_csv_reports/` directories.

Supported Default CSV Columns

When using the `–csv_columns` flag, only the following column names are supported. If you do not specify any custom columns, all of these default fields will be included automatically in the generated CSV report.

CSV_COLUMNS = [
# Container identity & status
"containerId","uuid","name","state","ipv4","ipv6", "created","updated","stateChanged","riskScore","qdsSeverity","maxQdsScore",
"imageId","imageSha","imageUuid","customerUuid","privileged","isRoot",
"isVulnPropagated","source","sensorUuid",
# Host / cluster info "host.sensorUuid","host.hostname","host.ipAddress",
"cluster.name","cluster.uid","cluster.version",
"cluster.k8s.pod.name","cluster.k8s.pod.namespace",
"cluster.k8s.pod.uuid",
"cluster.k8s.pod.controller[0].name","cluster.k8s.pod.controller[0].type",
"hostArchitecture",
# Runtime context
"environment","command","arguments"
# Vulnerability fields (one row per QID)
"vuln_qid","vuln_firstFound","vuln_lastFound","vuln_typeDetected","vuln_scanTypes",
# From vulnerability.software[] (joined if multiple)
"vuln_software_names","vuln_software_versions","vuln_software_fixVersions","vuln_software_packagePaths"
]

If you execute the command below without specifying `–csv_columns`, all the above columns will be included by default in the output CSV file:

python3 weeklycontainerreport.py https://gateway.qg2.apps.qualys.com

In the usage example, only a subset of these columns was chosen for simplicity. You may override and customize the output by specifying any subset from the supported list.

Platform Gateway URLs: https://www.qualys.com/platform-identification/

Script Execution Example

Sample CSV Output

Conclusion

By scheduling this script to run regularly, organizations can preserve complete visibility into their container environments, ensuring that audit, compliance, and historical analysis needs continue to be met seamlessly. This approach not only safeguards critical vulnerability data beyond the new 30-day retention period but also empowers teams to maintain durable, self-managed reporting pipelines as the Qualys platform evolves.

References

GitHub Repository: https://github.com/Qualys/cs-container-reports