ares

ares is a Python wrapper and CLI for the Vulnerability-Lookup API. It lets you query CVEs, EPSS scores, KEV catalogs, CWEs, and more — from Python code or directly from the terminal.

Requires Python 3.10+. Licensed under the Apache License 2.0.

Installation

pip install ares

This installs both the Python library (from ares import VulnLookup) and the ares-cli command-line tool.

For development:

pip install -e ".[dev]"

CLI

The ares-cli tool gives you direct access to the Vulnerability-Lookup API from your terminal. Output is JSON — pretty-printed to a terminal, compact when piped.

Examples

# Look up a specific vulnerability
ares-cli vuln get CVE-2024-1234

# Include metadata and comments
ares-cli vuln get CVE-2024-1234 --with-meta --with-comments

# Get the EPSS score for a CVE
ares-cli epss CVE-2024-1234

# Browse vendors, or products for a vendor
ares-cli browse
ares-cli browse apache

# Search vulnerabilities by vendor and product
ares-cli vuln search apache httpd --per-page 20

# Search by CPE string
ares-cli vuln cpe-search "cpe:2.3:a:apache:httpd"

# List CISA Known Exploited Vulnerabilities
ares-cli kev cisa

# Get CWE details
ares-cli cwe get 79

# View statistics
ares-cli stats vuln-count --state published --period 2024 --source cvelistv5
ares-cli stats most-sighted --limit 10

# Classify severity with VLAI
ares-cli classify "buffer overflow in the HTTP parser"

# Check database status
ares-cli system db-info

Global options

# Authenticate (option or env var)
ares-cli --api-key YOUR_KEY user me
export ARES_API_KEY=YOUR_KEY && ares-cli user me

# Query a self-hosted Vulnerability-Lookup instance
ares-cli --base-url https://my-instance.example.com/api browse

# Compact output for scripting
ares-cli --compact vuln list --product flask | jq '.[] .cveMetadata.cveId'

Command reference

Run ares-cli --help for the full command list, or ares-cli <command> --help for details on any command.

All list commands support --page and --per-page for pagination.

Python library

Basic usage

from ares import VulnLookup

# Use as a context manager (recommended — closes the HTTP session on exit)
with VulnLookup() as client:
    vuln = client.vulnerability("CVE-2024-1234")
    print(vuln["cveMetadata"]["state"])  # "PUBLISHED"

    epss = client.epss("CVE-2024-1234")
    print(epss["data"][0]["epss"])  # "0.064130000"

    vendors = client.browse()
    products = client.browse("apache")

Authentication

Some endpoints (write operations, user info) require an API key:

with VulnLookup(api_key="your-api-key") as client:
    me = client.me()
    print(me["login"])

Custom instance

Point to a self-hosted Vulnerability-Lookup instance:

client = VulnLookup(
    base_url="https://my-instance.example.com/api",
    timeout=30,
)

Searching vulnerabilities

with VulnLookup() as client:
    # List vulnerabilities with filters
    results = client.vulnerabilities(product="flask", source="cvelistv5", per_page=10)

    # Search by vendor and product
    results = client.search("apache", "httpd", per_page=20, since="2024-01-01")

    # Search by CPE
    results = client.cpe_search("cpe:2.3:a:apache:httpd")

    # Get a single vulnerability with extra data
    vuln = client.vulnerability(
        "CVE-2024-1234",
        with_meta=True,
        with_comments=True,
        with_sightings=True,
    )

KEV, CWE, CAPEC, EPSS

with VulnLookup() as client:
    # Known Exploited Vulnerabilities
    cisa = client.cisa_kev()
    cnw = client.cnw_kev()
    kevs = client.kevs(exploited=True)
    kev = client.kev("kev-uuid")

    # CWE / CAPEC / EMB3D details
    xss = client.cwe("79")
    capec = client.capec("1")
    technique = client.emb3d("T0001")

    # EPSS score
    epss = client.epss("CVE-2024-1234")

Bundles, comments, and sightings

with VulnLookup(api_key="your-api-key") as client:
    # Read
    bundles = client.bundles(vuln_id="CVE-2024-1234")
    comments = client.comments(vuln_id="CVE-2024-1234")
    sightings = client.sightings(type="exploited", vuln_id="CVE-2024-1234")

    # Write (require API key)
    client.create_bundle({"name": "my bundle", "description": "..."})
    client.create_comment({"title": "...", "vulnerability": "CVE-2024-1234"})
    client.create_sighting({"type": "seen", "vulnerability": "CVE-2024-1234"})

Automatic pagination

Every paginated method has a *_iter() variant that lazily fetches all pages:

with VulnLookup() as client:
    # Iterate over ALL vulnerabilities for a product (fetches pages on demand)
    for vuln in client.vulnerabilities_iter(product="flask", per_page=50):
        print(vuln["cveMetadata"]["cveId"])

    # Works with search too
    for vuln in client.search_iter("apache", "httpd", per_page=100):
        print(vuln["cveMetadata"]["cveId"])

Statistics

with VulnLookup() as client:
    count = client.stats_vulnerability_count(
        state="published", period="2024", source="cvelistv5",
    )
    sighted = client.stats_most_sighted(sighting_type="exploited", limit=10)
    vendors = client.stats_vendors_ranking(period="2024")
    cwes = client.stats_most_used_cwes(limit=10)

Error handling

All errors are subclasses of AresError:

from ares import VulnLookup, AresError, HTTPError

with VulnLookup() as client:
    try:
        client.vulnerability("CVE-9999-0000")
    except HTTPError as e:
        print(e.status_code)  # 404
        print(e.message)      # response body
    except AresError as e:
        # Connection failures, timeouts, invalid JSON
        print(e)

Logging

Enable debug logging to see HTTP requests and responses:

import logging
logging.basicConfig(level=logging.DEBUG)

# Now all requests are logged:
# DEBUG:ares:GET https://vulnerability.circl.lu/api/browse/ params=None
# DEBUG:ares:response 200 (1234 bytes)

Full method reference

All list methods accept page and per_page for pagination. Parameters set to None are omitted from the request. Every paginated method also has a *_iter() variant that lazily fetches all pages automatically.

License

Copyright 2014-2026 Martin Simon

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Buy me a coffee?

If you feel like buying me a coffee (or a beer?), donations are welcome:

BTC : bc1qq04jnuqqavpccfptmddqjkg7cuspy3new4sxq9
DOGE: DRBkryyau5CMxpBzVmrBAjK6dVdMZSBsuS
ETH : 0x2238A11856428b72E80D70Be8666729497059d95
LTC : MQwXsBrArLRHQzwQZAjJPNrxGS1uNDDKX6