Skip to content

HANDOFF.md

Latest commit

 

History

History
216 lines (165 loc) · 12 KB

HANDOFF.md

File metadata and controls

216 lines (165 loc) · 12 KB
Raw

Context Window Handoff — Paper 2: Temporal Vulnerabilities

Purpose: This document provides everything a new Claude Code session needs to resume work on this project without re-reading the entire corpus. Read this document first, then use the file references to go deeper on whatever phase you're executing.

Last updated: 2026-02-16 Current phase: Phase 0 (Documentation) — tasks 0.1.3 through 0.2.2 remain

1. What Is This Project?

An empirical study measuring whether frontier LLMs can detect vulnerabilities that require reasoning (race conditions, timing side-channels, compositional auth flaws) vs. vulnerabilities they already handle well (SQLi, command injection). This is Paper 2 in a two-paper series.

Paper 1 (completed): "Can Adversarial Code Comments Fool AI Security Reviewers?"

  • Found: adversarial comments barely affect detection (1.3pp drop)
  • Also found: 3 specific samples (TOCTOU, timing, Spring Security composition) were missed by ALL models, ALL prompts, ALL defenses
  • Location: ../adversarial-code-comments/

Paper 2 (this project): makes that incidental finding the central research question.

2. Key Files — Read These In Order

Priority File What It Contains
1 (always) HANDOFF.md This file — project state and resumption context
2 (for any work) RESEARCH-PLAN-FOR-REVIEW.md The complete research plan (v2) with all methodology, hypotheses, scoring design
3 (for execution) TASK-LIST.md Granular task list with dependencies and current status
4 (for sample writing) ../adversarial-code-comments/experiments/benchmark/samples/SAMPLE-009.json Paper 1's TOCTOU sample — the format template and the originating finding
5 (for scoring) ../adversarial-code-comments/experiments/tools/scorer.py Paper 1's scorer — the starting point for Tier 1 adaptation
6 (for scoring) ../adversarial-code-comments/experiments/tools/config.py Paper 1's model registry — reuse and extend
7 (for literature) toctou/ directory (8 survey documents) Deep literature reviews covering all three vulnerability classes

3. Critical Design Decisions (Don't Re-Litigate)

These decisions have been reviewed and validated. Don't change them without explicit user instruction:

  1. Three-tier scoring: Tier 1 (binary detection, automated) → Tier 2 (correct class + minimal evidence criteria, automated) → Tier 3 (reasoning quality rubric, judge-model + human audit). This was the single most important methodological improvement over Paper 1.

  2. Control-A vs Control-B split: Control-A (pure pattern: SQLi, command injection, hardcoded creds) is the only baseline used for the primary gap metric (H1). Control-B (path traversal, deserialization) is secondary/gradient analysis. This prevents inflating the gap by including semi-reasoning controls.

  3. 30 decoy samples (10 per reasoning category): Decoys look like the vulnerability but are properly mitigated (e.g., TOCTOU-like with proper locking). They measure false positive rate and validate that models are reasoning, not pattern-matching.

  4. SP4a/SP4b split: SP4a = real SAST output (whatever tools actually produce). SP4b = oracle hint from ground truth (standardized minimal hint). The gap between them measures the value of building better SAST rules. SAST rarely fires for timing/compositional, making SP4a inconsistent across categories — SP4b provides the consistent signal.

  5. Reasoning × Context 2×2 label: Every sample labeled reasoning_depth: low/high and context_completeness: complete/partial. Primary claims use only context_completeness: complete samples. This blocks the "maybe the model just needed more context" reviewer critique.

  6. Pre-registered capability boundary: A category is a "capability boundary" only if all three hold: Tier 1 < 50%, Tier 3 median < 0.4, and decoy FPR > 20% or flip rate > 30%.

  7. Languages: Python, Java, Go, JavaScript. C was deliberately dropped (toolchain complexity, minimal marginal signal).

  8. 10 models: 8 from Paper 1 + o3-mini + DeepSeek-R1 (reasoning models). Temperature 0.3, 3 runs per condition.

4. Paper 1 Infrastructure Reuse Map

The Paper 1 experiment tooling is at ../adversarial-code-comments/experiments/tools/. Here's what carries over and what needs adaptation:

Paper 1 File Reuse Status Adaptation Needed
config.py Reuse + extend Add o3-mini, DeepSeek-R1 to MODELS dict. Add SP3/SP4a/SP4b prompt templates. Update paths to Paper 2 directories
runner.py Reuse + extend Add API client handling for o3-mini (OpenAI reasoning API, may return reasoning tokens). DeepSeek-R1 may need special handling
models.py Reuse Provider routing logic (OpenAI, Anthropic, Gemini, DeepSeek, Perplexity, Ollama) should work as-is
scorer.py Reuse as Tier 1 only The keyword-based detection scoring becomes Tier 1. Needs new keyword lists for temporal/side-channel/compositional. Add "no vulnerabilities" pattern list for new domains
run_experiment.py Adapt New CLI args: --variant {C0,C1,C_hint}, --prompt {SP0,SP3,SP4a,SP4b}, --runs 3, --category {temporal,side-channel,compositional,control-a,control-b}
analyze.py Extend Add new metrics (Tier 2, Tier 3, decoy FPR, flip rate, run variance). Add new figure generation
defenses.py Not reused Paper 1 defense conditions (comment stripping, dual-pass, etc.) don't apply here

New files to create:

  • class_scorer.py — Tier 2 with minimal evidence criteria
  • reasoning_judge.py — Tier 3 dual-judge pipeline
  • stability_analyzer.py — flip rate, run variance, confidence-correctness
  • decoy_scorer.py — FP tracking for decoy samples

5. Sample Format

Paper 2 extends Paper 1's JSON format. The canonical reference sample is Paper 1's SAMPLE-009.json (TOCTOU). Paper 2 samples add these fields:

{
  "sample_id": "TEMPORAL-001",          // new prefix convention
  "category": "temporal",               // {temporal, side_channel, compositional, control_a, control_b}
  "subcategory": "database_toctou",     // specific subcategory
  "language": "python",
  "difficulty": "hard",
  "ground_truth": "vulnerable",         // {vulnerable, safe} — safe for decoys
  "reasoning_depth": "high",            // {low, high} — NEW
  "context_completeness": "complete",   // {complete, partial} — NEW
  "presentation": "single_file",        // {single_file, multi_file} — NEW
  "concurrency_model": "true_concurrency", // temporal only — NEW
  "side_channel_subtype": null,         // side-channel only: {timing, information_oracle} — NEW
  "vulnerability": {
    "type": "...",
    "cwe": "CWE-367",
    "severity": "high",
    "location": {"start_line": 28, "end_line": 40},
    "description": "...",
    "keywords": ["..."],               // same as Paper 1 — used for Tier 1
    "reasoning_chain": [               // NEW — used for Tier 3 scoring
      "Step 1: identify check operation",
      "Step 2: identify use operation",
      "Step 3: recognize no atomic bridging",
      "Step 4: determine exploitation path",
      "Step 5: conclude exploitability"
    ],
    "correct_mitigation": "..."        // NEW — secondary metric
  },
  "code_variants": {
    "C0_no_comments": "...",           // same format as Paper 1
    "C1_annotated": "...",             // C1 replaces Paper 1's C1_accurate
    "C_hint": "..."                    // NEW — replaces Paper 1's C2-C7
  },
  "sast_confirmation": {
    "tool": "bandit",
    "finding": "...",
    "confirmed": true                  // false for side-channel/compositional where SAST can't see it
  },
  "exploitation_preconditions": ["..."]
}

Decoy samples use "ground_truth": "safe" and have no reasoning_chain. They are scored for false positives only.

6. Current Phase Status

Update this section whenever you complete work.

Phase 0: Plan Review & Documentation

  • 0.1.1 Draft research plan (v1)
  • 0.1.2 Incorporate review feedback (v2)
  • 0.1.3 Create task list
  • 0.1.4 Create handoff document (this file)
  • 0.1.5 Update auto-memory
  • 0.1.6 Send to external reviewers (Scott, manual)
  • 0.1.7 Incorporate reviewer feedback into v3
  • 0.2.1 Create directory structure
  • 0.2.2 Create sample JSON schema
  • 0.2.3 Fork and adapt Paper 1 tools (config.py, models.py, runner.py, scorer.py)
  • 0.2.4 Create DGX test package for open-source model validation

Phase 1: Literature Finalization — NOT STARTED

Phase 2: Benchmark Construction — NEXT (build temporal sample templates)

Phase 3: Scoring Pipeline — Tier 1 scorer complete, Tier 2/3 pending

Phase 4: Experiment Execution — NOT STARTED

Phase 5: Scoring & Audit — NOT STARTED

Phase 6: Analysis & Writing — NOT STARTED

Phase 7: Submission — NOT STARTED

7. Session Resumption Protocol

When starting a new session on this project:

  1. Read this file (HANDOFF.md) — you're doing this now
  2. Check Section 6 for current phase status
  3. Read the relevant section of TASK-LIST.md for the current phase's granular tasks
  4. If writing samples: Read RESEARCH-PLAN-FOR-REVIEW.md §4 (taxonomy) and §5 (benchmark design) for requirements. Read one existing Paper 1 sample (SAMPLE-009.json) for format reference
  5. If building scoring pipeline: Read RESEARCH-PLAN-FOR-REVIEW.md §7 (scoring) and check Paper 1 tools at ../adversarial-code-comments/experiments/tools/
  6. If running experiments: Read RESEARCH-PLAN-FOR-REVIEW.md §6 (experimental design) and check experiments/tools/config.py for model registry
  7. If writing the paper: Read RESEARCH-PLAN-FOR-REVIEW.md §9 (expected outputs) and §13 (paper outline)
  8. Update Section 6 of this file before ending your session

8. Key Numbers (Quick Reference)

Metric Value
Total samples 160 (130 vulnerable + 30 decoy)
Comment variants 3 (C0, C1, C_hint)
Models 10
System prompts 4 (SP0, SP3, SP4a, SP4b)
Runs per condition 3
Total evaluations ~33,600
Estimated API cost $1,500-2,200
Estimated total cost $2,100-3,200
Timeline 11-15 weeks from Phase 1
Target venue USENIX Security 2026 (fall)
Paper length ~15 pages + appendix

9. Hypothesis Quick Reference

H# One-Line Summary Expected Outcome
H1 Reasoning categories detected less than controls Control-A ≥85%, Temporal ≤40%, Side-Channel ≤25%, Compositional ≤50%
H2 Reasoning prompt (SP3) helps reasoning categories more Temporal/comp: +10-25pp. Side-channel: +5-15pp. Control: <5pp
H3 Accurate comments help reasoning categories more >15pp lift for temporal, <5pp for control
H4 Commercial/open-source gap narrows at Tier 1, persists at Tier 3 Tier 1 gap <10pp on reasoning. Tier 3 gap ~15pp
H5 Code-specialized models don't help for reasoning No significant difference
H6 SAST/oracle hints partially close the gap Real SAST: +10-15pp where it fires. Oracle: +15-25pp
H7 Reasoning models better but still below controls o3-mini/R1: +10-20pp over standard, still <60%

10. What NOT to Do

  • Don't re-read the 8 literature survey documents in toctou/ unless you're doing Phase 1 literature finalization. They're already synthesized into the research plan.
  • Don't change the sample counts or category definitions without updating both RESEARCH-PLAN-FOR-REVIEW.md and TASK-LIST.md. These are pre-registered.
  • Don't build the scoring pipeline before samples exist. The Tier 3 rubric depends on actual reasoning chains from real samples.
  • Don't mix Control-A into Control-B or vice versa. The split is intentional and the primary gap metric depends on it.
  • Don't score decoys with the same pipeline as vulnerable samples. Decoys are scored for false positives (FP/TN), not true positives (TP/FN).

This document should be the FIRST thing read in any new session working on Paper 2.