function-index

---
name: "function-index"
description: "Look up, filter, and resolve functions using function_index.json files generated by DeepExtractIDA for each extracted module. Map function names to their .cpp files, filter application code from library boilerplate (WIL/STL/WRL/CRT/ETW), list module functions with statistics, and resolve function names to absolute file paths. Use when locating a function's source file, filtering boilerplate from application code, listing functions in a module, resolving function names to paths for reading, or when another skill needs to find which .cpp file contains a specific function."
license: "MIT"
---

# Function Index

## Purpose

Provide fast function-to-file resolution for DeepExtractIDA extraction outputs. Every extracted module folder contains a `function_index.json` that maps each function name to the `.cpp` file containing its decompiled output, plus a library tag for boilerplate detection. This skill provides scripts to query, filter, and resolve these indexes without scanning hundreds of `.cpp` files.

**This skill is designed to be reused by other skills** -- it does not depend on any other skills.

## When NOT to Use

- Extracting full function data (decompiled code, assembly, xrefs) -- use **decompiled-code-extractor**
- Classifying functions by purpose or computing interest scores -- use **classify-functions**
- Searching across strings, APIs, and classes (not just function names) -- use `unified_search.py` or **decompiled-code-extractor**
- Understanding what a function does -- use **re-analyst** or `/explain`
- Tracing call chains between functions -- use **callgraph-tracer**

## Data Sources

Each module folder under `extracted_code/{module}/` contains:

- `function_index.json` -- lightweight index mapping function names to files and library tags
- `file_info.json` -- full module metadata (signatures, imports, exports, etc.)
- `{module}_*.cpp` -- grouped decompiled source files

### function_index.json Format

```json
{
  "<function_name>": {
    "file": "module_standalone_group_5.cpp",
    "library": null
  },
  "<wil_function>": {
    "file": "module_standalone_group_1.cpp",
    "library": "WIL"
  }
}
```

| Field       | Description                                                                 |
| ----------- | --------------------------------------------------------------------------- |
| `file`      | The `.cpp` filename in the same directory as the index                      |
| `library`   | Library tag: `WIL`, `STL`, `WRL`, `CRT`, `ETW/TraceLogging`, or `null`     |

`library = null` means application code. Non-null tags identify known library/runtime boilerplate.

For full format details, see [function_index_format_reference.md](../../docs/function_index_format_reference.md).

## Utility Scripts

All scripts are in `scripts/`. Auto-resolve workspace root and `.claude/helpers/` imports. Run from the workspace root.

### lookup_function.py -- Find Functions by Name (Start Here)

Locate a function across one or all modules. Supports exact match, substring search, and regex.

```bash
# Exact lookup across all modules
python .claude/skills/function-index/scripts/lookup_function.py AiCheckSecureApplicationDirectory

# Exact lookup in a specific module
python .claude/skills/function-index/scripts/lookup_function.py AiCheckSecureApplicationDirectory --module appinfo_dll

# Substring search (case-insensitive)
python .claude/skills/function-index/scripts/lookup_function.py --search "CheckSecure"

# Regex search
python .claude/skills/function-index/scripts/lookup_function.py --search "Ai.*Launch" --regex

# Application code only (skip WIL/STL/WRL/CRT/ETW boilerplate)
python .claude/skills/function-index/scripts/lookup_function.py --search "Check" --app-only

# JSON output
python .claude/skills/function-index/scripts/lookup_function.py --search "BatLoop" --json
```

Output: module name, `.cpp` file, library tag, and full path for each match.

### index_functions.py -- List and Filter Module Functions

List all functions in a module, filter by library tag, group by file, or show statistics.

```bash
# List all functions in a module
python .claude/skills/function-index/scripts/index_functions.py appinfo_dll

# Only application code
python .claude/skills/function-index/scripts/index_functions.py appinfo_dll --app-only

# Only WIL boilerplate
python .claude/skills/function-index/scripts/index_functions.py appinfo.dll --library WIL

# Group by .cpp file
python .claude/skills/function-index/scripts/index_functions.py appinfo_dll --by-file

# Functions in a specific .cpp file
python .claude/skills/function-index/scripts/index_functions.py appinfo_dll --file appinfo_dll_standalone_group_5.cpp

# Statistics only
python .claude/skills/function-index/scripts/index_functions.py appinfo_dll --stats

# Stats for all modules
python .claude/skills/function-index/scripts/index_functions.py --all --stats

# JSON output
python .claude/skills/function-index/scripts/index_functions.py appinfo_dll --app-only --json
```

### resolve_function_file.py -- Resolve to Absolute Paths

Resolve function names to absolute `.cpp` file paths. Designed for programmatic use by other scripts and skills.

```bash
# Single function -> absolute path
python .claude/skills/function-index/scripts/resolve_function_file.py AiCheckSecureApplicationDirectory

# Within a specific module
python .claude/skills/function-index/scripts/resolve_function_file.py AiCheckSecureApplicationDirectory --module appinfo_dll

# Batch resolve (comma-separated)
python .claude/skills/function-index/scripts/resolve_function_file.py --names "AiCheckLUA,AiLaunchProcess,BatLoop"

# All functions in a .cpp file
python .claude/skills/function-index/scripts/resolve_function_file.py --file appinfo_dll_standalone_group_5.cpp --module appinfo_dll

# JSON output
python .claude/skills/function-index/scripts/resolve_function_file.py AiCheckSecureApplicationDirectory --json
```

Default output format (pipe-delimited for parsing): `module|file_path|library_tag`

## Unified Search (Cross-Dimensional)

When you don't know if the target is a function name, string literal, API call, or class name, use the unified search helper to search all dimensions in one call:

```bash
# Search everything for "CreateProcess" in a module DB
python .claude/helpers/unified_search.py <db_path> --query "CreateProcess"

# JSON output for programmatic use
python .claude/helpers/unified_search.py <db_path> --query "registry" --json

# Search only names and API calls
python .claude/helpers/unified_search.py <db_path> --query "Token" --dimensions name,api

# Search across ALL module DBs
python .claude/helpers/unified_search.py --all --query "CreateProcess"
```

Searches: function names, signatures, string literals, API calls, dangerous APIs, class names (from mangled names/vtable contexts), and exports. Returns results grouped by match dimension. Use `--json` for machine-readable output.

**Use this when**: you're not sure where a term appears (is it a function name? a string? an API it calls?), or when you want a quick overview of everything related to a search term in one command.

## Workflows

### Workflow 1: "Where is function X defined?"

```bash
# Step 1: Look up by exact name
python .claude/skills/function-index/scripts/lookup_function.py CreateElevatedProcess

# Step 2: If not found, try substring search
python .claude/skills/function-index/scripts/lookup_function.py --search "Elevated"

# Step 3: Read the resolved .cpp file
# (use the file_path from the output)
```

### Workflow 2: "What application functions does module X have?"

```bash
# Step 1: Get stats to understand the module
python .claude/skills/function-index/scripts/index_functions.py appinfo_dll --stats

# Step 2: List only application code (skip boilerplate)
python .claude/skills/function-index/scripts/index_functions.py appinfo_dll --app-only

# Step 3: Group by file to see how they're organized
python .claude/skills/function-index/scripts/index_functions.py appinfo_dll --app-only --by-file
```

### Workflow 3: "Read the code for functions A, B, and C"

```bash
# Step 1: Resolve all functions to their file paths
python .claude/skills/function-index/scripts/resolve_function_file.py --names "FuncA,FuncB,FuncC" --module appinfo_dll --json

# Step 2: Read each resolved file path
# (the JSON output provides absolute paths to each .cpp file)
```

### Workflow 4: "Overview of all extracted modules"

```bash
python .claude/skills/function-index/scripts/index_functions.py --all --stats
```

## Integration with Other Skills

This skill provides the function-to-file mapping that other skills need. The core logic lives in **`helpers/function_index/`**, making it importable by any script that has `.claude` on `sys.path` -- the same pattern used by `helpers/analyzed_files_db/` and `helpers/individual_analysis_db/`.

Use it as a **first step** before:

- **code-lifting**: Find both the `.cpp` file and confirm function exists before extracting from DB
- **classify-functions**: Pre-filter application code before classification
- **batch-lift**: Resolve a batch of function names to files
- **data-flow-tracer**: Locate functions to trace
- **callgraph-tracer**: Identify which module contains a function

### Importing from Other Skills' Scripts

Any script that already has the standard `.claude` path setup can use the helpers directly:

```python
from helpers import (
    load_function_index,
    resolve_module_dir,
    filter_by_library,
    lookup_function,
    resolve_function_file,
    list_extracted_modules,
    is_application_function,
)

# Resolve a function to its absolute .cpp path (searches all modules)
cpp_path = resolve_function_file("AiCheckLUA")

# Look up with module + file details
matches = lookup_function("BatLoop")
# -> [{"function_name": "BatLoop", "module": "cmd_exe", "file": "...", "file_path": "...", "library": None}]

# Load a module's full index and filter to app code
index = load_function_index("appinfo_dll")
app_funcs = filter_by_library(index, app_only=True)

# Resolve module folder
mod_dir = resolve_module_dir("appinfo.dll")  # accepts both appinfo.dll and appinfo_dll
```

### Full Helper API

Available via `from helpers import ...` or `from helpers.function_index import ...`:

| Function                    | Returns                                     | Purpose                                            |
| --------------------------- | ------------------------------------------- | -------------------------------------------------- |
| `load_function_index(mod)`  | `dict` or `None`                            | Load a module's function_index.json                |
| `load_all_function_indexes()` | `dict[str, dict]`                         | Load indexes for all modules                       |
| `lookup_function(name, mod?)` | `list[dict]`                              | Find function across one/all modules (exact match) |
| `resolve_function_file(name, mod?)` | `Path` or `None`                    | Resolve function name to .cpp path                 |
| `resolve_module_dir(mod)`   | `Path` or `None`                            | Module name to extracted_code dir                  |
| `list_extracted_modules()`  | `list[str]`                                 | All module folders with function_index.json        |
| `filter_by_library(idx, ...)` | `dict`                                    | Filter by library/app_only/lib_only                |
| `is_application_function(entry)` | `bool`                                 | True if library tag is null                        |
| `is_library_function(entry)` | `bool`                                     | True if library tag is set                         |
| `group_by_file(idx)`        | `dict[str, list[str]]`                      | Group functions by .cpp file                       |
| `group_by_library(idx)`     | `dict[str\|None, list[str]]`               | Group functions by library tag                     |
| `compute_stats(idx)`        | `dict`                                      | Total/app/lib counts, breakdown, file count        |
| `function_index_path(mod)`  | `Path` or `None`                            | Absolute path to function_index.json               |

## Library Tags

| Tag               | Description                                             | Examples                                              |
| ----------------- | ------------------------------------------------------- | ----------------------------------------------------- |
| `null`            | Application code -- the module's own logic              | `AiCheckLUA`, `BatLoop`, `CSyncMLDPU::AppendStatus`  |
| `WIL`             | Windows Implementation Library (telemetry, RAII)        | `wil::details::...`, `wistd::...`                     |
| `STL`             | C++ standard library                                    | `std::vector<>`, `stdext::...`                        |
| `WRL`             | Windows Runtime C++ Template Library (COM support)      | `Microsoft::WRL::...`                                 |
| `CRT`             | C/C++ runtime support                                   | `__scrt_*`, `__acrt_*`, `_CRT_*`                      |
| `ETW/TraceLogging`| TraceLogging and ETW telemetry helpers                  | `_tlgWrite*`, `TraceLoggingCorrelationVector::*`      |

**Tip**: For most analysis tasks, use `--app-only` to skip boilerplate and focus on the module's actual logic.

## Performance

| Operation | Typical Time | Notes |
|-----------|-------------|-------|
| Index functions (build) | ~3-8s | Full module indexing |
| Lookup single function | <1s | JSON index search |
| Resolve function file | <1s | Maps function name to .cpp file |
| Unified search | ~1-2s | Cross-dimensional search |

## Additional Resources

- [reference.md](reference.md) -- Full JSON schema, library tag detection patterns, edge cases, script argument reference, helper API quick reference
- [function_index_format_reference.md](../../docs/function_index_format_reference.md) -- full format spec
- [file_info_format_reference.md](../../docs/file_info_format_reference.md) -- file_info.json schema (signatures, imports, exports)
- [data_format_reference.md](../../docs/data_format_reference.md) -- SQLite DB schema and JSON field formats
- [code-lifting](../code-lifting/SKILL.md) -- code lifting skill (uses DB helpers)