<name>

Category: Tools & Productivity | Uploader: Entropy1110 | Downloads: 0 | Version: v1.0（Latest）
<One-line description>
Changelog: Source: GitHub https://github.com/Entropy1110/kernel_claude_skills
Directory Structure

Current level: .claude/skills/add-target/
📄 skill.md 10.4 KB
SKILL.md

# Add Target

Scaffold a new analysis target: skill, framework config, pre-flight check, and config preset.

## Description

This skill creates all files needed to add a new static analysis target to the pipeline:
1. `.claude/skills/<name>-analyze/skill.md` — Skill definition with execution guide
2. `.claude/skills/<name>-analyze/pre-flight-check.sh` — Environment validation script
3. `configs/<name>.yaml` — Framework config (entrypoint patterns, indicators, FP rules, prompt context)
4. Preset entry in `.claude/config/config.json`
5. Framework auto-registration via `configs/<name>.yaml` discovery

Important naming note:
- Stage commands currently use legacy `mali-*` names.
- New target onboarding must clearly document both:
  - full pipeline via `/<name>-analyze`
  - stage-by-stage via `/mali-map -> /mali-triage -> ...` with `--framework=<name>`

## Execution Guide for Claude Code

**IMPORTANT**: When this skill is invoked, follow these steps in order:

### Step 1: Gather Target Information (MANDATORY)

**You MUST ask the user these questions using AskUserQuestion before proceeding:**

#### Question 1: Target Name
Ask: "What short name should I use for this target? (used in filenames, CLI flags, output dirs)"
- Must be lowercase, no spaces, alphanumeric + hyphens only
- Examples: `vb2`, `ext4`, `binder`, `ion`, `netfilter`, `btrfs`

#### Question 2: Repository Path
Ask: "Where is the source code repository?"
- Absolute path to the repo root (e.g., `~/linux`)

#### Question 3: Scope
Ask: "What directory should be analyzed? (relative to repo root)"
- e.g., `drivers/media/common/videobuf2`, `fs/ext4`, `drivers/android`

#### Question 4: Code Type
Ask: "What type of code is this?"
Options:
- "Linux kernel subsystem" — kernel driver, filesystem, networking, etc.
- "ARM firmware (EL3/S-EL1)" — TF-A, OP-TEE, TF-M style
- "User-space C/C++" — applications, libraries, daemons

### Step 2: Research the Target (CRITICAL)

**Before creating any files, you MUST understand the target's architecture.**

Read source files in the target directory to identify:

1. **Entrypoint patterns** — How does external input reach this code?
   - ioctl handlers, file_operations callbacks, syscall handlers
   - RPC/IPC entry points, network packet handlers
   - Exported API functions, callback registrations
   - Look for structs like `file_operations`, `proto_ops`, `ioctl` dispatch tables

2. **Lifecycle stages** — What are the init/runtime/cleanup phases?
   - Module init/exit, probe/remove, open/release
   - Object creation/destruction sequences
   - State machine transitions

3. **Framework guarantees** — What does the framework ensure?
   - Reference counting patterns (kref, refcount, custom)
   - Locking hierarchies
   - Memory ownership rules
   - Lifecycle ordering constraints

4. **User-controlled data paths** — Where does untrusted input flow?
   - copy_from_user/copy_to_user, get_user/put_user
   - Network buffers, shared memory, file data
   - ioctl argument structs

5. **Common vulnerability patterns** — What bugs are typical for this subsystem?
   - Integer overflows in size calculations
   - Use-after-free from refcount errors
   - TOCTOU races
   - Missing validation on user-supplied lengths/offsets
   - Lock ordering violations

6. **Guard patterns** — What validation functions protect against bugs?
   - Bounds checks, type validation, access rights checks
   - Capability checks, permission validation

**Spend real time reading the code.** The quality of the framework config directly determines analysis quality.

### Step 3: Create Framework Config (`configs/<name>.yaml`)

Create `configs/<name>.yaml` following this structure exactly:

```yaml
framework:
  name: "<name>"
  display_name: "<Human Readable Name>"
  description: "<One-line description>"

lifecycle:
  stages:
    - name: "initialization"
      functions: [<init functions found in Step 2>]
      description: "<description>"
    - name: "runtime"
      functions: [<runtime functions found in Step 2>]
      description: "<description>"
    - name: "cleanup"
      functions: [<cleanup functions found in Step 2>]
      description: "<description>"

  guarantees:
    - "<guarantee 1 from Step 2>"
    - "<guarantee 2>"

entrypoint_patterns:
  <category>:
    - regex: "<pattern>"
      field: "<field_name>"
    # For patterns that extract function names:
    - regex: "<pattern with capture group>"
      field: "<field_name>"
      func_group: 1

indicator_patterns:
  user_control:
    - "<regex>"
  lifetime:
    - "<regex>"
  concurrency:
    - "<regex>"
  guards:
    - "<regex>"

false_positive_rules:
  - pattern: "<regex>"
    reason: "<why this is a false positive>"
    auto_downgrade: true
    target_risk: "low"

prompt_context:
  role: "<analyst role description>"
  framework_knowledge: |
    ## <Framework> Checklist
    <Detailed knowledge from Step 2>

  false_positive_examples:
    - title: "<example title>"
      code: |
        <code snippet>
      wrong_analysis: "<what a naive analyzer would say>"
      correct_analysis: "<why it's actually safe>"
      key_insight: "<the key thing to understand>"
```

**Key rules:**
- All regex patterns must use `\\b` for word boundaries (double-escaped in YAML)
- `func_group: 1` tells the mapper to extract the function name from capture group 1
- Include at least 2-3 false_positive_examples based on real code from the target
- `framework_knowledge` should be comprehensive — this is what guides the LLM analysis
- `indicator_patterns` categories MUST include: `user_control`, `lifetime`, `concurrency`, `guards`

### Step 4: Create Skill Definition (`.claude/skills/<name>-analyze/skill.md`)

Create the skill.md following the pattern of existing skills. Use this template:

```markdown
# <Name> Static Analysis (Full Pipeline)

Run complete vulnerability analysis on <target description> C code.

## Description
[Same 7-step pipeline description as other skills]

## Execution Guide for Claude Code
[Same 8-step execution guide, customized with:]
- Step 1: Check `out/<name>/` for existing results
- Step 2: Target presets specific to this target
- Step 3: Pre-flight check path: `.claude/skills/<name>-analyze/pre-flight-check.sh`
- Step 5: `--framework=<name>`
- Step 7: Vulnerability checklist specific to this target (from Step 2 research)
- Step 7.5: Read `out/<name>/report_true_positives.md` first (pipeline may create placeholder), then write final report
- Step 8: `out/<name>/report_true_positives.md`

## Usage
/<name>-analyze --repo=<default_repo> --scope=<default_scope>

## Usage Order
1. Fast path: `/<name>-analyze --repo=<repo> --scope=<scope>`
2. Stage path:
   - `/mali-map --repo=<repo> --scope=<scope> --framework=<name> --session-id=<id>`
   - `/mali-triage --session-id=<id>`
   - `/mali-deep-dive --session-id=<id>`
   - `/mali-classify --session-id=<id>`
   - `/mali-followup --session-id=<id>` (optional)
   - `/mali-report --session-id=<id>`
3. Clarify that `mali-*` stage prefixes are legacy labels and still valid for all targets.

## Parameters
[Standard parameter table]

## Framework: <Display Name>
[Bullet list of key entrypoint categories and patterns]

## Output
[Standard output section pointing to out/<name>/]
```

### Step 5: Create Pre-Flight Check (`.claude/skills/<name>-analyze/pre-flight-check.sh`)

Create the pre-flight check script. It's identical across all targets except for:
- The header message: `=== <Name> Static Analysis Pre-Flight Check ===`
- The output directory check: `out/<name>/report.md`

Make it executable: `chmod +x .claude/skills/<name>-analyze/pre-flight-check.sh`

### Step 6: Add Config Preset

Edit `.claude/config/config.json` to add the new target to `targets.presets`:

```json
"<name>": {
  "repo": "<repo_path>",
  "scope": "<scope>",
  "framework": "<name>"
}
```

Add any useful sub-scope presets too (e.g., if the target has distinct subsystems).

### Step 7: Framework Auto-Discovery (No Python Edit Needed)

Do **not** edit Python files to register frameworks.

Frameworks are auto-discovered from `configs/*.yaml`, so creating `configs/<name>.yaml` is enough for:
1. `skill_runner.py --framework`
2. `static_ai.py --framework`

### Step 7b: Scaffold PoC Directory

Create the PoC directory for the new target from the template:

```bash
mkdir -p poc/<name>/env
cp poc/_template/poc_template.c poc/<name>/
cp poc/_template/Makefile poc/<name>/
cp poc/_template/kernel.config poc/<name>/
cp poc/_template/env/build.sh poc/<name>/env/
cp poc/_template/env/run.sh poc/<name>/env/
chmod +x poc/<name>/env/*.sh
```

Update the copied files with target-specific values (compiler, module, device path, QEMU options).

### Step 8: Verify

Run these checks:
```bash
# Config loads without error
.venv/bin/python -c "from framework_config import load_framework_config; c = load_framework_config('<name>'); print(f'OK: {c.display_name}')"

# Skill runner recognizes the framework
.venv/bin/python skill_runner.py run-full-pipeline --help | rg -- '<name>'

# CLI auto-discovers the new framework from configs/<name>.yaml
.venv/bin/python static_ai.py --help | rg -- '<name>'

# Pre-flight check runs
bash .claude/skills/<name>-analyze/pre-flight-check.sh --force --repo=<repo> --scope=<scope>
```

### Step 9: Document Execution Order (MANDATORY)

In the generated `.claude/skills/<name>-analyze/skill.md`, explicitly include:
1. Fast path command (`/<name>-analyze`)
2. Stage-by-stage commands in exact order:
   - `/mali-map --framework=<name> --session-id=<id>`
   - `/mali-triage --session-id=<id>`
   - `/mali-deep-dive --session-id=<id>`
   - `/mali-classify --session-id=<id>`
   - `/mali-followup --session-id=<id>` (optional)
   - `/mali-report --session-id=<id>`
3. A note that `mali-*` prefixes are legacy labels, not framework restrictions.

### Step 10: Present Summary

Tell the user:
- Files created (skill.md, pre-flight-check.sh, config yaml)
- Files modified (config.json)
- How to invoke fast path: `/<name>-analyze`
- How to invoke stage path: `/mali-map ... -> /mali-report`
- Suggest running a `--test` analysis to validate

## Usage

```
/add-target
```

The skill will interactively gather information and scaffold all files.

## Parameters

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| (interactive) | - | - | All parameters gathered via AskUserQuestion |

## Output

Files created:
- `.claude/skills/<name>-analyze/skill.md`
- `.claude/skills/<name>-analyze/pre-flight-check.sh`
- `configs/<name>.yaml`

Files modified:
- `.claude/config/config.json` (preset added)
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
<name>

Directory Structure

SKILL.md

Report

Notice
