web3-vulnerability-database

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

web3-vulnerability-database

★ 25 Open GitHub ↗

Web3 Vulnerability Database

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Web3 Vulnerability Database

A curated, machine-validated database of reusable Web3 vulnerability classes
for security researchers and automated audit workflows.

## CLI tool

Example: vulnerability types for tokenized lending vaults:

```bash
bun run db search \
  --domain lending \
  --category lending.share-accounting \
  --capability vault.tokenized-shares \
  --format json \
  | jq '.records[1] | {
      id,
      title,
      category: .routing.primaryCategory,
      status: .reviewStatus
    }'
```

```json
{
  "id": "lending.conversion-pair-rounds-toward-the-caller",
  "title": "A vault's asset and share conversions round toward the caller, so a round trip returns more than it cost",
  "category": "lending.share-accounting",
  "status": "draft"
}
```

Render a result as Markdown:

```bash
bun run db show lending.empty-vault-share-inflation --format markdown
```

```markdown
## Preconditions

A lending vault issues fungible shares against pooled assets, computes conversions from the current asset and share totals,
and can reach a zero or very small share supply. Assets can enter the vault without minting proportional shares,
such as through a direct transfer, accrued yield, debt repayment, or another donation-like path.
...
```

## TypeScript integration

Use the same query engine programmatically with the committed catalog and
category registry:

```ts
import catalog from "./catalog.json";
import categoryRegistry from "./config/categories.json";
import { queryCatalog } from "@aviggiano/web3-vulnerability-database/query";

const result = queryCatalog(
  catalog,
  {
    domains: ["lending"],
    categories: ["lending.share-accounting"],
    capabilities: ["vault.tokenized-shares"],
  },
  { categories: categoryRegistry.categories },
);

for (const record of result.records) {
  console.log(record.id, record.title, record.sha256);
}
```

## Corpus

These views are generated from validated class records and the protocol-type
registry.

[![Vulnerability taxonomy forest showing category namespaces, categories, and class routing](https://raw.githubusercontent.com/aviggiano/web3-vulnerability-database/main/docs/assets/vulnerability-taxonomy.svg)](docs/assets/vulnerability-taxonomy.svg)

[![Alphabetical protocol-type registry showing core, extended, and deferred curation tiers](https://raw.githubusercontent.com/aviggiano/web3-vulnerability-database/main/docs/assets/protocol-type-registry.svg)](docs/assets/protocol-type-registry.svg)

The taxonomy forest places each class at its one primary category. `P` counts
primary class assignments, `S` counts secondary category routes, and `C` counts
categories in a namespace. The protocol directory presents protocol types as
peers: `C`, `E`, and `D` mean `core`, `extended`, and `deferred`. Protocol types
organize evidence curation; they do not determine whether a vulnerability class
applies to a target.

See the [data model](docs/explanation/data-model.md) for the distinction between
classification and applicability, the [protocol-type
registry](docs/reference/protocol-types.md) for tier semantics, and the
[accessible chart data](docs/reference/corpus-overview.md) for exact counts and
IDs. The [database contract](docs/reference/database-contract.md) defines the
catalog and digest guarantees.

## Documentation

The documentation follows [Diátaxis](https://diataxis.fr/) and separates four
kinds of reader need:

- [Tutorials](docs/tutorials/index.md) teach the workflow through a complete example.
- [How-to guides](docs/how-to/index.md) solve specific authoring and ingestion tasks.
- [Reference](docs/reference/index.md) defines commands, schemas, registries, and artifacts.
- [Explanation](docs/explanation/index.md) describes the model and its design choices.

## Development

Class records live at `classes/<domain>/<slug>.yml`. To extend the corpus, use
the [class-authoring guide](docs/how-to/author-vulnerability-classes.md). To
gather and classify new public evidence, use the
[ingestion guide](docs/how-to/ingest-findings.md).

Run the complete local gate set before opening a pull request:

```bash
bun run check
bun test
bun run schema:check
bun run docs:check
bun run db generate --check
bun run db validate
bun run check:auditvault
bun run check:pinned
```

Solodit ingestion reads `SOLODIT_API_KEY` only for `probe` and `fetch`. Raw
source bodies, API responses, and normalized working data stay in the ignored
`.work/` directory. See the [data-model explanation](docs/explanation/data-model.md)
for the evidence, applicability, provenance, and licensing boundaries.

Repository-authored code, schemas, documentation, and curated class text are
licensed under the [MIT License](LICENSE). Linked source material remains under
its respective terms.

web3-vulnerability-database

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README