Coverity Metrics

A Python toolkit that turns Coverity Connect's PostgreSQL database into interactive HTML dashboards, terminal reports, and portable ZIP exports — including quarter-over-quarter trend reports that run entirely offline.

Contents

• What you get
• Quick start
• Installation
• Configuration
• CLI reference
• Workflows
• Python library
• Documentation index
• Security notes
• License

What you get

Dashboard tabs cover Overview, Code Quality, Performance & Analytics, Trends & Progress (with technical-debt estimation), Leaderboards, OWASP Top 10 2025, CWE Top 25 2025, and — in ZIP mode — Snapshots.

Per-release detail lives in CHANGELOG.md and RELEASE_NOTES.md.

Quick start

pip install coverity-metrics
cp config.json.example config.json
# Edit config.json with your database credentials

coverity-dashboard                 # DB mode; opens output/dashboard.html in your browser
coverity-metrics                   # Terminal-only text report
coverity-export --output exports   # Portable ZIP for offline delivery

No admin / root rights? Use pip install --user coverity-metrics or pipx install coverity-metrics, or grab a standalone binary from the GitHub Releases page — see INSTALL.md for details.

Installation

From PyPI

pip install coverity-metrics

Installs the three CLI commands (coverity-dashboard, coverity-metrics, coverity-export) and coverity-delta, plus the python -m coverity_metrics <subcommand> entry point.

From source

git clone https://github.com/lejouni/coverity_metrics.git
cd coverity_metrics
pip install -e .

Standalone binaries

Windows and Linux single-file binaries are published on every tagged release — see packaging/README.md. They ship their own Python runtime so no Python install is required on the target host.

Requirements

• Python ≥ 3.10 (transitive requirement from pandas ≥ 3.0)
• Runtime deps installed automatically: pg8000, pandas, python-dateutil, jinja2, plotly, tqdm

Configuration

config.json

One instance is enough for single-instance mode. Add more to enable multi-instance aggregation.

{
  "instances": [
    {
      "name": "Production",
      "description": "Production Coverity Instance",
      "enabled": true,
      "database": {
        "host": "coverity-server.company.com",
        "port": 5432,
        "database": "cim",
        "user": "coverity_ro",
        "password": "your_password_here"
      },
      "color": "#2c3e50"
    }
  ],
  "aggregated_view": {
    "enabled": true,
    "name": "All Instances"
  }
}

• 2+ enabled instances → multi-instance mode (auto-detected).
• aggregated_view.enabled: true turns on the cross-instance dashboard.
• Add config.json to .gitignore before your first commit.

Detailed multi-instance setup is in MULTI_INSTANCE_GUIDE.md.

Finding the DB credentials in Coverity Connect

The values live in cim.properties under the Coverity Connect install directory:

Map each property into config.json or the matching env var:

Notes:

• The password is stored in cleartext in cim.properties. Only the Coverity Connect service user should have read access to that file.
• The bundled PostgreSQL that ships with Coverity Connect listens on port 5433 by default (not 5432). Copy whatever port the properties file has.
• Prefer creating a dedicated read-only role in Postgres and granting pg_read_all_data — the tool never issues DML.

Environment-variable mode

coverity-export and coverity-dashboard (DB mode only) can run without a config.json when all required env vars are set. Handy in CI pipelines and containers.

Startup precedence (both tools):

1. --config <file> explicitly passed → load that JSON.
2. All required env vars set → single-instance env-var mode.
3. config.json in the current directory → loaded automatically.
4. Otherwise → exit with guidance.

Example (PowerShell):

$env:COVERITY_DB_HOST     = "coverity-prod.company.com"
$env:COVERITY_DB_NAME     = "cim"
$env:COVERITY_DB_USER     = "coverity_ro"
$env:COVERITY_DB_PASSWORD = "***"
$env:COVERITY_INSTANCE_NAME = "Production"
coverity-export    --output exports --days 365
coverity-dashboard --output output  --days 365 --no-browser

coverity-metrics still requires config.json; env-var mode is coverity-export / coverity-dashboard-only.

Pre-built quickstart scripts under scripts/ — coverity-export.sh (Linux) and coverity-export.ps1 (Windows) — download the standalone binary, source these variables from a block at the top of the script, and run one export in one shot.

CLI reference

coverity-dashboard

Reads from a database or from one or more coverity-export ZIPs. Auto-detects multi-instance from config.json.

Detailed caching / performance tuning is in CACHING_GUIDE.md; multi-ZIP behaviour is in MULTI_ZIP_GUIDE.md.

coverity-metrics

Terminal text report. Uses the first enabled instance from config.json unless --zip-file is given.

Redirect stdout to save (coverity-metrics > report.txt).

coverity-export

Creates one ZIP per enabled instance. Each ZIP is self-contained (all instance and per-project JSONs, metadata, and optional snapshot / leaderboard sections) and is the input for coverity-dashboard --zip-file and coverity-delta.

ZIP filenames follow {output}/coverity_export_{InstanceName}_{YYYYMMDD_HHMMSS}.zip.

coverity-delta

Turns two or more coverity-export ZIPs sitting in a folder into a chronological trend report (delta.json + inline-SVG dashboard_delta.html). Runs entirely offline.

coverity-delta --archive-dir archive/ --output delta/latest

Guardrails, timing tags on Added / Dropped lists, rank movement on Defects-by-project, and the full CLI surface are documented in the Trend comparison workflow below and in EXPORT_QUICKSTART.md.

Workflows

Daily / weekly / monthly

coverity-metrics                                # fast terminal check
coverity-dashboard --cache                      # visual dashboard (opens in browser)
coverity-dashboard --cache --days 90            # tighter trend window for a review
coverity-export --output exports --days 365     # snapshot for archival / delivery

Offline delivery (single instance)

# On a machine with DB access
coverity-export --days 365 --output deliverables

# Ship the ZIP anywhere (email, USB, file share).
# On the receiving machine (no DB required):
coverity-dashboard --zip-file deliverables/coverity_export_Production_*.zip

Multi-ZIP aggregation

Combine ZIPs from separate Coverity servers (different networks, different regions) into a single set of dashboards:

coverity-dashboard --zip-file exports/*.zip --aggregated-view --no-browser

• --aggregated-view is off by default; it's the sole opt-in.
• Passing --config path/to/config.json with zip_files_config.aggregated_view.enabled: true is an equivalent opt-in — either source alone is enough.
• Duplicate instance names across ZIPs (all labelled Production even though they came from different servers) are disambiguated automatically by appending the ZIP filename's stem in parentheses — e.g. Production (prod_us), Production (prod_eu).
• * / ? / […] wildcards are expanded inside the tool, so the same command works on Linux, macOS, and Windows (PowerShell / cmd) without needing shell-side globbing.

More detail: MULTI_ZIP_GUIDE.md.

Trend comparison (multi-quarter trends)

Run coverity-export at the end of every period with the same --days value and the same --mapping-file, letting the ZIPs accumulate in a shared archive folder. Then point coverity-delta at the folder:

# End of every quarter — same --days and --mapping-file across runs.
coverity-export --days 90 \
    --anonymize --mapping-file archive/shared-mapping.json \
    --output archive/

# When you have two or more ZIPs in archive/:
coverity-delta --archive-dir archive/ --output delta/latest

Two or more ZIPs are required; there is no upper bound. Snapshot labels auto-derive to YYYY-QN from each ZIP's export_date; override positionally with --labels a,b,c,... when the auto labels collide.

The report covers five metric families — Projects, Active users, Scan activity, Stream activity, and Defects-by-project (with inline SVG sparklines and rank movement) — and hard-fails on mismatched --days or mismatched anonymization mappings across the archive. Full guardrail behaviour and CLI flags in EXPORT_QUICKSTART.md.

Anonymized delivery

coverity-export --anonymize
# → exports/coverity_export_Production_YYYYMMDD_HHMMSS.zip           (safe to share)
# → exports/coverity_export_Production_YYYYMMDD_HHMMSS.mapping.json  (keep private)

# Keep ids stable across re-exports (recommended for trend workflows):
coverity-export --anonymize --mapping-file ./anon-map.json

Only project and stream names are replaced. Host, database name, and user / committer names are not anonymized in the current release.

Python library

from coverity_metrics import CoverityMetrics, MultiInstanceMetrics, InstanceConfig

metrics = CoverityMetrics(
    connection_params={
        "host": "localhost",
        "port": 5432,
        "database": "coverity",
        "user": "postgres",
        "password": "your_password",
    },
    project_name="MyProject",  # optional filter
)

# Top-N results (default) or all rows via fetch_all
categories = metrics.get_defects_by_checker_category(limit=10)
hotspots   = metrics.get_file_hotspots(fetch_all=True)

# Technical debt, security compliance, leaderboards
debt   = metrics.get_technical_debt_summary()
owasp  = metrics.get_owasp_top10_metrics()
cwe25  = metrics.get_cwe_top25_metrics()
fixers = metrics.get_top_users_by_fixes(days=30, limit=10)

Multi-instance aggregation is the same shape:

instances = [
    InstanceConfig("Production",  {...connection_params...}),
    InstanceConfig("Development", {...connection_params...}),
]
multi = MultiInstanceMetrics(instances)
aggregated = multi.get_aggregated_metrics()

Every metric method returns a pandas.DataFrame. Methods that support fetch_all accept (limit=N, fetch_all=False); setting fetch_all=True ignores limit. See USAGE_GUIDE.md for the full method reference and additional examples.

Documentation index

Security notes

• Database passwords land in config.json in cleartext — treat it like any other credential file.

• Add config.json (and any *.mapping.json) to .gitignore before your first commit.

• Prefer read-only DB credentials (pg_read_all_data) — the tool issues no DML.

• Restrict file permissions on the config file:

  chmod 600 config.json     # Linux / macOS
  

• For CI, use env-var mode with your platform's secret store instead of shipping a config file.

• --anonymize masks project and stream names in shared ZIPs; the <zip>.mapping.json sidecar stays private and is the only way to decode the ids back.

License

Provided as-is for use with Coverity installations. See LICENSE.