Share
## https://sploitus.com/exploit?id=09B905C6-CD97-54E6-AD97-B0DD1AC4771B
# CVE KB: A high-quality knowledge base for automatic penetration testing agents

This is a project dedicated to building and retrieving knowledge about CVEs for automatic penetration testing agents/RAG systems. Its goal is not to simply dump PoC or vulnerability articles into a vector database, but to organize publicly available PoC signals, vulnerability metadata, attack surface information, and exploitation hints into highly informative knowledge cards suitable for large model retrieval and reasoning. This project is particularly useful for the following scenarios:
- Retrieving vulnerability knowledge for automatic penetration testing agents
- Quickly identifying vulnerabilities in CTFs/penetration competitions
- Retrieving CVEs related to cloud security, Kubernetes, AI infrastructure, identity systems, CI/CD
- Recalling CVE candidates, exploitation instructions, and detection methods within RAG systems

## What does this project solve?

Using directly the full text of `PoC-in-GitHub` or vulnerability articles for embedding typically results in several issues:
- Excessive noise; README files, blog posts, and page templates can contaminate vector semantics
- Unstable hit rates; searching for a product name may lead to incorrect results
- Lack of structured fields, making it difficult for agents to determine “whether it’s exploitable”
- No attack chain relationships, nor target identification fingerprints

This project will organize these raw signals into:
- Structured main CVE records
- Overviews, exploits, and detection chunks suitable for embedding
- BM25 keyword indexes
- Attack chain diagrams
- Attack surface fingerprint libraries
- Exploit/detection texts for use by agents

In short, this is not a “vulnerability data archiving project,” but rather a “CVE retrieval foundation for automated penetration testing agents.” ## Core capabilities of the project

The current system supports:
- Building CVE knowledge bases from `PoC-in-GitHub`
- Generating structured `records.jsonl` files
- Generating `chunks.jsonl` files suitable for RAG
- Creating BM25 retrieval indexes
- Generating attack chain diagrams `chain_graph.json`
- Creating target identification fingerprint libraries `fingerprints.jsonl`
- Supporting three retrieval modes: `bm25`, `hybrid`, and `vector`
- Supporting exploit chunks, detection chunks, and fingerprint matching
- Supporting fine-grained tags for cloud security, Kubernetes, AI infrastructure, identity systems, CI/CD

## Explanation of the repository structure

Below are the most important files in this repository and their functions. ### Unified entry point

- `kb.py`
  - This is the recommended entry point
  - Responsible for providing unified access to `build`, `query`, `exploit`, `detect`, `chain`, `fingerprint`, and `ingest` functions
  - If you only use this project, you generally only need to remember this file

### Build entry point

- `build_cve_kb.py`
  - A more low-level build CLI
  - Suitable when you want to pass more detailed parameters yourself
  - It actually calls `cve_kb_builder.builder.build_corpus`

### Retrieval entry point

- `retriever.py`
  - Local retriever
  - Supports:
    - `bm25` retrieval
    - `hybrid` retrieval
    - `vector` retrieval
    - Retrieving exploit chunks based on CVEs
    - Retrieving detection chunks based on CVEs
    - Checking attack chain candidates
    - Reversing candidate CVEs based on target fingerprints
  - This file is very important if you plan to integrate it into an agent later

### Vector storage entry point

- `ingest.py`
  - Embeds `chunks.jsonl` into FAISS
  - The `hybrid` and `vector` modes rely on the vector library generated by this file
  - If you only run BM25 first, you may not need this file immediately

### Bridge between agents/playground

- `bridge.py`
  - Converts `records.jsonl` into a format that’s easier for agents to consume
  - Suitable for integrating with your own playground or agent framework

### Manual template refinement

- `curated_overrides.example.json`
  - Templates for manually overriding high-value CVEs
  - Suitable for manually correcting tags, descriptions, and exploitation hints before competitions

## Detailed explanation of the `cve_kb_builder/` directory

This directory contains the core logic of the entire project. 
- `cve_kb_builder/builder.py`
  - Main builder
  - Responsible for integrating PoC data, NVD, EPSS, KEV, README, reference, etc. into the final knowledge base
  - Outputs:
    - `records.jsonl`
    - `chunks.jsonl`
    - `bm25_docs.jsonl`
    - `bm25_index.json`
    - `chain_graph.json`
    - `fingerprints.jsonl`

- `cve_kb_builder/taxonomy.py`
  - Taxonomy and rule system
  - Responsible for generating:
    - `vuln_types`
    - `asset_tags`
    - `platform_tags`
    - `domain_tags`
    - `cloudtags`
    - `k8stags`
    - `ai_infrastags`
    - `identitytags`
    - `cicdtags`

## Description of output files after building

After building, the following files are typically found in the output directory:

- `records.jsonl`
  - Complete, structured main CVE records
  - Suitable for storing main data

- `chunks.jsonl`
  - Chunks for vector retrieval/RAG
  - Usually contains:
    - `overview`
    - `exploit`
    - `detection`

- `bm25_docs.jsonl`
  - Collection of BM25 documents

- `bm25_index.json`
  - BM25 index
  - One of the most important files for keyword retrieval

- `chain_graph.json`
  - Graph of candidate attack chains
  - Helps the agent identify potential linked CVEs from one CVE

- `fingerprints.jsonl`
  - Database of target identification fingerprints
  - Suitable for inferring candidate vulnerabilities based on ports, paths, headers, protocols

- `summary.json`
  - Build statistics
  - Includes number of records, number of chunks, top tags, etc.

## Recommended GitHub repository structure

It is recommended to keep only source code and instructions in the public source repository. Do not include large data sources and build artifacts directly. ```text
. ├─ kb.py
├─ build_cve_kb.py
├─ retriever.py
├─ ingest.py
├─ bridge.py
├─ curated_overrides.example.json
├─ pyproject.toml
├─ README.md
├─ .gitignore
└─ cve_kb_builder/
   ├─ __init__.py
   ├─ builder.py
   ├─ indexing.py
   ├─ models.py
   ├─ sources.py
   └─ taxonomy.py
```

## Content not recommended for submission to GitHub

These generally should not be included in the public source repository:
- `source_repo/`
  - Original `PoC-in-GitHub` mirror, too large
- `out-`
  - Build artifacts, not source code
- `vectordb/`
  - Vector index artifacts
- `__pycache__/`
  - Python cache files
- `.pytest_cache/`
  - pytest cache files
- `.claude/`
  - Local tool configurations

## Quick start

### 0. Prepare data sources

First, clone `PoC-in-GitHub` to your local machine:

```bash
git clone https://github.com/nomi-sec/PoC-in-GitHub.git source_repo
```

By default, the project will read data from `source_repo/`. ### 1. Quickly build a locally accessible knowledge base

```bash
python kb.py build
```

Default behavior:
- Data source directory: `source_repo`
- Output directory: `out-prod`
- Year range: `2024 2025 2026`

This step is in “quick availability mode”, allowing you to quickly get a searchable large database. ### 2. Query CVEs

```bash
python kb.py query "Langflow unauthenticated RCE public flow build endpoint"
```

### 3. View exploitation descriptions for a specific CVE

```bash
python kb.py exploit CVE-2026-33017
```

### 4. View detection descriptions for a specific CVE

```bash
python kb.py detect CVE-2026-33017
```

### 5. Query candidate attack chains

```bash
python kb.py chain CVE-2026-33017
```

### 6. Reverse engineer candidate vulnerabilities based on target fingerprints

```bash
python kb.py fingerprint "port 7860 open, /api/v1/build_public_tmp returns 200, server uvicorn, langflow"
```

## Higher-quality builds

### Increase online enrichment

```bash
python kb.py build --online
```

This will additionally obtain:
- NVD
- EPSS
- CISA KEV

### Additional Deep Content Acquisition

```
python kb.py build --online --deep
```

This will further acquire:
- PoC README
- Payload segments from the reference page
- Patch difference signals

## Vector Retrieval / Hybrid Retrieval

By default, `bm25` retrieval does not require embedding. If you want to enable `vector/hybrid`, first write the chunk into FAISS:

```
python kb.py ingest
```

In Windows PowerShell:

```
$env:OPENAI_API_KEY="your_key_here"
python kb.py ingest
```

### Installing Vector-Related Dependencies

```
pip install langchain-core langchain-community langchain-openai faiss-cpu
```

### Hybrid/Vector Query Examples

```
python kb.py query "Kubernetes ingress admission controller RCE" --mode hybrid
python kb.py query "Langflow workflow RCE" --mode vector
```

## Overview of Common Commands

### Building

```
python kb.py build
python kb.py build --online
python kb.py build --online --deep
python kb.py build --years 2023 2024 2025 2026
python kb.py build --cves CVE-2024-3400 CVE-2024-6387 CVE-2026-33017
python kb.py build --focus-profile tencent
```

### Queries

```
python kb.py query "OpenSSH sshd race condition unauthenticated signal handling"
python kb.py query "Palo Alto GlobalProtect command injection firewall unauthenticated" --top-k 10
python kb.py query "Kubernetes ingress admission controller RCE" --mode bm25
```

### Extracting Specific Content

```
python kb.py exploit CVE-2024-3400
python kb.py detect CVE-2024-6387
python kb.py chain CVE-2026-33017
```

### Fingerprint Matching

```
python kb.py fingerprint "port 22 open, ssh banner OpenSSH"
python kb.py fingerprint "port 7860 open, /api/v1/flows returns 200, server uvicorn"
```

## Tag System

This project not only assigns coarse-grained tags but also fine-grained ones. ### Coarse-Grained Tags

- `vuln_types`
- `asset_tags`
- `platform_tags`
- `domain_tags`

### Fine-Grained Tags

- `cloudtags`
- `k8stags`
- `ai-infratags`
- `identitytags`
- `cicdtags`

Examples:
- `workflow_orchestration`
- `model_serving`
- `ingress`
- `api_server`
- `jwt`
- `pipeline_engine`
- `runner_agent`
- `artifact_registry`

## A Typical Data Flow

```
PoC-in-GitHub JSON
  -> Structured CVE records
  -> Exploit recipes
  -> Retrieved chunks
  -> BM25 index
  -> Chain graph
  -> Fingerprint library
  -> Optional FAISS vector index
```

## Target Audience

This project is particularly suitable for:
- Developers of automatic penetration testing agents
- People working on CVE RAG retrieval
- Teams participating in penetration testing competitions/CTFs
- Those interested in cloud security, K8s, and AI infrastructure vulnerability knowledge bases

## Notes

- It is not recommended to directly submit `PoC-in-GitHub` images to this repository.
- It is also not recommended to directly submit `out-*` build outputs to this repository.
- The best way to share it publicly is with source code, README files, and sample templates.
- Before actual competitions, it is recommended to manually refine high-value CVEs to cover more areas.

## One-Sentence Description

A system for building and retrieving highly informative CVE knowledge bases for automatic penetration testing agents/RAG systems. Supports BM25, vector retrieval, attack chains, exploitation instructions, detection descriptions, and attack surface fingerprints.