george203/Encryption-Side-Channel-Attack

# Side-Channel Attack Assistant An agentic side-channel auditor. An LLM agent drives a set of power-analysis tools to evaluate a masked AES-128 implementation for leakage, recover key bytes, and recommend countermeasures. Built against the public ASCAD dataset. ## What it does ## Setup Requires Python 3.10+. python3 -m venv .venv source .venv/bin/activate pip install h5py numpy scipy matplotlib anthropic Download the ASCAD v1 fixed-key dataset (ATMega8515) from https://github.com/ANSSI-FR/ASCAD and place the file at `data/ASCAD.h5`. Put an Anthropic API key in a `.env` file at the repo root: ANTHROPIC_API_KEY=sk-ant-... ## Running Run the agent: python3 agent/run_session.py data/ASCAD.h5 The default model is `claude-sonnet-4-6`. For a stronger run: python3 agent/run_session.py data/ASCAD.h5 --model claude-opus-4-7 Run the non-agent baseline as a ground-truth check: python3 baseline/manual_cpa.py data/ASCAD.h5 --plot Each agent session writes a log to `logs/session_.md`. ## Architecture The harness (`agent/run_session.py`) runs the Claude API in a tool-use loop, dispatching tool calls to Python functions in `tools/` and logging the session. The agent follows the audit protocol in `agent/system_prompt.md`: load, profile with SNR, attempt first-order CPA across three leakage models, detect masking, escalate to second-order CPA, verify recovery, and write the report. | Tool | Purpose | |---|---| | `load_ascad` | Load traces and labels | | `compute_snr` | Signal-to-noise per sample | | `select_poi` | Point-of-interest selection (snr, sost, ttest) | | `select_mask_poi` | Locate where the mask leaks | | `run_cpa` | First-order CPA (hw_sbox, id_sbox, hd models) | | `run_cpa_2nd` | Second-order CPA | | `run_template` | Gaussian template attack | | `compute_guessing_entropy` | Rank and guessing-entropy curve | ## Example sessions Two logged runs are included in `logs/`: - `session_20260528_144025.md`: first-order tools only. The agent diagnoses masking from the SNR profile and reports that the implementation resists a first-order adversary. - `session_20260602_183118.md`: full pipeline. The agent detects masking, locates the mask leakage, escalates to second-order CPA, and recovers key byte 2 (0xE0) at rank 1, rated CRITICAL. ## Dataset note ASCAD v1 fixed-key is a first-order Boolean masked AES-128 implementation. All 16 key bytes are masked, and the 700-sample trace window is aligned to byte 2's SubBytes operation, so byte 2 is the target. First-order CPA leaves byte 2 at the random-guess baseline. The second-order tools combine the mask leakage with the masked value to recover the key. ## Layout agent/ agent harness and system prompt tools/ power-analysis tool implementations baseline/ non-agent CPA for ground truth logs/ session logs data/ ASCAD.h5 (not committed)