# AI-VULNATLAS Sample Dataset

This directory contains a small public-ready sample of AI-related vulnerability analysis data. Each project directory follows the same layout so repository context, module taxonomy, and vulnerability-level findings can be reviewed together.

## Projects

- `MervinPraison_PraisonAI`
- `openclaw_openclaw`
- `qhkm_zeptoclaw`

## Directory Layout

```text
<project_key>/
|-- project-github-info.json
|-- wiki/
|   |-- manifest.yaml
|   `-- deepwiki/pages/
|-- modules/
|   |-- project-group.json
|   |-- <project_key>-cluster-module.json
|   |-- <project_key>-taxonomy.md
|   `-- module-assignments.<project_key>.json
`-- findings/
    `-- <CVE-or-GHSA-id>/
        |-- README.md
        |-- vuln-description.txt
        |-- module-localization.json
        |-- ai-participation.json
        |-- denoise/
        |-- vuln-features/
        `-- standard-classification/
```

## Project-Level Data

### `project-github-info.json`

GitHub repository metadata for the sampled project. Important fields include:

- `project_key` / `project_id`: dataset project identifier.
- `github_url`, `full_name`, `description`, `homepage`: repository identity and public metadata.
- `stars`, `forks`, `watchers`, `open_issues`, `size_kb`: repository statistics.
- `primary_language`, `languages_json`, `language_breakdown`: language metadata.
- `created_at`, `updated_at`, `pushed_at`, `fetched_at_utc`: repository and fetch timestamps.
- `license`, `topics`, `default_branch`, `fetch_status`, `fetch_error`: additional GitHub metadata.

### `wiki/`

Project documentation context collected from public documentation sources.

- `manifest.yaml`: inventory of included DeepWiki pages. Page `path` values are relative to the project `wiki/` directory.
- `deepwiki/pages/`: DeepWiki page markdown files.

### `modules/`

Project-level module analysis artifacts.

- `project-group.json`: coarse functional group for the project, with `group_id`, `group_name`, and `description`.
- `<project_key>-cluster-module.json`: module map for the project. Each `modules[]` item includes `module_id`, `module_name`, `description`, `kind`, and `code_location`.
- `<project_key>-taxonomy.md`: human-readable taxonomy for the module IDs.
- `module-assignments.<project_key>.json`: compact list of module assignment records, with `repo_id`, `group_id`, `module_id`, `module_name`, and `kind`.

## Finding-Level Data

Each vulnerability is stored under `<project_key>/findings/<CVE-or-GHSA-id>/`.

### `vuln-description.txt`

Vulnerability description material used as the finding-level input.

### `module-localization.json`

Vulnerability-to-module localization result.

Key fields:

- `vuln_module`: localized module object.
- `vuln_module.module_id`, `vuln_module.module_name`: module assigned to this vulnerability.
- `vuln_module.confidence`: confidence in the module assignment.
- `vuln_module.is_ai_native`: whether the affected module is AI-native.
- `vuln_module.code_location`: relevant paths, files, classes, or functions.
- `vuln_module.why_vulnerable`: explanation for why this module is implicated.
- `vuln_category`: high-level category, such as `traditional` or `ai_feature_dependent`.
- `traditional_cwe`: closest traditional CWE mapping when applicable.
- `ai_mechanism`: explanation of the AI-specific mechanism when applicable; otherwise `null`.
- `would_exist_without_ai`: whether the same vulnerability mechanism would still exist without AI functionality.
- `category_confidence`, `category_reasoning`: confidence and rationale for the category.

### `ai-participation.json`

AI participation analysis across two rounds.

Key fields:

- `rounds[]`: per-round analysis record.
- `rounds[].round`: local round label, such as `r1` or `r2`.
- `rounds[].source_round`: original analysis round label, such as `R3` or `R4`.
- `rounds[].module_id`, `rounds[].group_key`: module and grouping used by that analysis round.
- `rounds[].leaf_stats.ai_related`: aggregate counts for `true`, `false`, and `both` labels in that leaf group.
- `rounds[].vuln.ai_related`: round-level AI participation conclusion. Values may be boolean `true`/`false` or string `"both"` when both model-mediated and direct paths are present.
- `rounds[].vuln.attack_chain`: summarized attack chain.
- `rounds[].vuln.model_in_chain`: explanation of whether and how the model participates.
- `comparison`: compact comparison between rounds when both rounds are present.

### `denoise/`

Multi-model denoise/verifier outputs for the vulnerability.

Included model directories:

- `deepseek`
- `glm`
- `gpt-5.5cyber`
- `kimi`

Each model directory keeps final result artifacts:

```text
denoise/<model>/verify_requirements/
|-- root_cause.md
`-- sast_standardized.json
```

`denoise/summary.json` summarizes the included model outputs. Each `models[]` item includes `model`, `files`, optional `summary`, and a compact `finding` object.

`sast_standardized.json` contains a verifier result with:

- `if_verify`: whether the model/verifier judged the finding as verified.
- `summary`: verifier summary.
- `findings`: standardized finding records.

### `vuln-features/feature-result.json`

Final vulnerability feature extraction output.

Key fields:

- `ai_involvement_final`: final AI involvement label. Values include `"true"`, `"both"`, or `"mixed_true_false"`.
- `has_model_path`: boolean indicating whether a model-mediated attack path exists.
- `has_direct_path`: boolean indicating whether a direct non-model path exists.
- `model_path_summary`, `direct_path_summary`: path summaries.
- `ai_role`, `ai_role_evidence`: model role and supporting evidence.
- `entry_surface`, `exposed_capability`, `architecture_layer`: affected surface and capability labels.
- `missing_arch_control`, `trust_boundary_failure`: missing control and trust-boundary labels.
- `traditional_mechanism`: traditional vulnerability mechanism.
- `function_dependency_class`: whether the issue is traditional, AI-feature-dependent, or otherwise categorized.
- `paper_example_candidate`: boolean flag for whether the finding is a strong paper example candidate.
- `needs_human_review`, `review_reason`: review flag and rationale.

Fields ending in `_other` contain free-text labels when the controlled vocabulary did not fit cleanly. Fields ending in `_evidence` contain supporting rationale.

### `standard-classification/`

Matching/evaluation outputs against three AI vulnerability classification standards:

- `cycode.json`
- `giskard.json`
- `owasp.json`

`summary.json` lists the included standard files and their top-level keys.

## Excluded Files

The sample intentionally excludes local environment files, process logs, run logs, operating-system metadata, timing artifacts, and intermediate validation outputs. Only final analysis outputs and compact summaries are included.
