Extending the GCVE Python cli with a vulnerability lookup command

GCVE
,
1

The idea is to extend the GCVE Python CLI with a vulnerability lookup command inspired by dig (Domain Information Groper).

I initially considered implementing a new sub-command named vig, but I am not a fan of the name. I also dislike the term “groper”. After exploring various alternatives, I think vlookup is clear, concise, and descriptive.

Usage

This tool will be used as a command-line utility to retrieve information about a vulnerability directly from the shell, using authoritative GNA compliant servers. For instance, a Vulnerability-Lookup instance operated by a GNA. It should also be compatible with any GCVE-BCP-03 compliant service.

Optionally, it could eventually be integrated into a future web service, for example available at registry.gcve.eu, or vulnerability.gcve.eu, etc.

And why not used in Vulnerability-Lookup.

Examples

Some examples of what I would like to implement:

Simple query

$ gcve vlookup GCVE-1337-2025-00000000000000000000000000000000000000000000000001011011111110011111111110000000000000000000000000000000000000000000000000000000010
{
    "gna-id": 1337
    "gcve_pull_api": "https://aha-gcve.todb.workers.dev/"
    "vulnerability": "GCVE-1337-2025-00000000000000000000000000000000000000000000000001011011111110011111111110000000000000000000000000000000000000000000000000000000010"
}

By default it will query GNA-1337 since the GNA id is in the vulnerability id. If nothing is found it will start to query servers from the GNA directory until it gets an answer.
So we could get:

$ gcve vlookup GCVE-1337-2025-00000000000000000000000000000000000000000000000001011011111110011111111110000000000000000000000000000000000000000000000000000000010
{
    "gna-id": 1337
    "gcve_pull_api": "https://example.com/"
    "vulnerability": "GCVE-1337-2025-00000000000000000000000000000000000000000000000001011011111110011111111110000000000000000000000000000000000000000000000000000000010"
}

Query with more information

$ gcve vlookup --full GCVE-1337-2025-00000000000000000000000000000000000000000000000001011011111110011111111110000000000000000000000000000000000000000000000000000000010
{
    "gna-id": 1337
    "":
    "gcve_pull_api": "https://aha-gcve.todb.workers.dev/"
    "vulnerability": {<- JSON DATA ->}
}

Query a specific server

$ gcve vlookup --server GNA-1 GCVE-1337-2025-00000000000000000000000000000000000000000000000001011011111110011111111110000000000000000000000000000000000000000000000000000000010
{
    "gna-id": 1337
    "gcve_pull_api": "https://vulnerability.circl.lu/api/"
    "vulnerability": "GCVE-1337-2025-00000000000000000000000000000000000000000000000001011011111110011111111110000000000000000000000000000000000000000000000000000000010"
}

This will query the server behind the GNA-1 operated by CIRCL Luxembourg. In this case, if nothing is found, it won’t ask to an other server.

I first thought about using the symbol @ from dig, but again I think it’s not a good idea. Maybe as an alias.

Trace mode

$ gcve vlookup <id> --trace
Shows the lookup path:
;; Querying GNA-1337 first...
;; Not found, trying GNA-42...
;; Found at https://vulnerability.circl.lu/api/

Suggested cli design

gcve vlookup [options] <vulnerability_id>...

Options:
  -h, --help          Show this help message and exit
  -s, --server GNA    Query a specific GNA server (no fallback)
  --full              Return full JSON data
  --trace             Show lookup path

Seems enough for a first version.

3 Likes
2

the JSON output in the examples is really a draft. I see more something like:

{
  "vulnerability_id": "GCVE-1337-2025-0000000000000000101",
  "gna_id": 1337,
  "sources": [
    {
      "gna": "GNA-1337",
      "api": "https://aha-gcve.todb.workers.dev/",
      "found": true,
      "timestamp": "2025-10-24T21:00:00Z",
      "vulnerability": {<- JSON DATA ->}
    }
  ],
  "fallback_attempted": false
}
3

This is an awesome idea.

Maybe an option to add the pivot metadata when we have the relationships with the other ID but that could be for the next version and when BCP-05 is finally published.

4

sure, why not ! I’ll start with the basic idea and see how it goes.

1 Like