Chipsec Static Analysis Skill - Implementation Plan

Chipsec Static Analysis Skill - Implementation Plan

Status: IMPLEMENTED

Overview

This plan outlines the implementation of a Claude Code skill for UEFI firmware static analysis using chipsec. The skill focuses exclusively on offline static analysis capabilities - analyzing firmware dump files without requiring kernel driver access or root privileges.

Skill Name: chipsec (changed from chipsec-uefi for simplicity)

Scope

In Scope (Static Analysis Only)

• Firmware image decoding and structure analysis
• EFI executable inventory and hash generation
• Malware/rootkit detection (blocklist scanning)
• NVRAM/UEFI variable extraction from dumps
• Baseline generation and comparison
• Known vulnerability pattern matching (ThinkPwn, LoJax, etc.)

Out of Scope (Live System Analysis - Requires Separate Skill)

• SPI flash dumping from live systems
• BIOS write protection checks
• SMM security testing
• Secure Boot live verification
• Intel Boot Guard checks
• Any module requiring kernel driver

Skill Structure

.claude/skills/chipsec/
├── SKILL.md                    # Main skill file with instructions
├── WORKFLOWS.md                # Common analysis workflows
└── BLOCKLIST_REFERENCE.md      # Known threats reference (optional)

SKILL.md Design

Frontmatter

---
name: chipsec-uefi
description: Static analysis of UEFI firmware dumps using chipsec. Decode firmware structure, detect known malware/rootkits (LoJax, ThinkPwn, HackingTeam), extract EFI executable inventories, and analyze NVRAM variables. Use when analyzing firmware .bin/.rom/.fd files offline.
---

Key Sections

1. Tool Overview

• What chipsec is (Intel's Platform Security Assessment Framework)
• Focus on offline/static capabilities
• Prerequisites (chipsec installed, logs directory writable)

2. Prerequisites Check

# One-time fix for chipsec logging issue
sudo mkdir -p /usr/lib/python3.13/site-packages/logs
sudo chmod 777 /usr/lib/python3.13/site-packages/logs

3. Core Commands

A. Generate EFI Executable Inventory

chipsec_main -i -n -m tools.uefi.scan_image -a generate <output.json> <firmware.bin>

• Creates JSON manifest of all EFI modules with SHA256 hashes
• Use for baseline/change detection

B. Malware/Vulnerability Scan

chipsec_main -i -n -m tools.uefi.scan_blocked -a <firmware.bin>

• Checks against known threats:
  • HackingTeam UEFI Rootkit
  • MosaicRegressor UEFI Rootkit
  • LoJax (first wild UEFI rootkit)
  • ThinkPwn SMM vulnerability
  • FirmwareBleed SMM vulnerability

C. Firmware Structure Decoding

chipsec_util -i -n uefi decode <firmware.bin>

• Extracts firmware volumes, files, sections
• Creates output directory with components

D. NVRAM Variable Extraction

chipsec_util -i -n uefi nvram vss <firmware.bin>
chipsec_util -i -n uefi nvram nvar <firmware.bin>

• Extracts stored UEFI variables
• VSS format (common) and NVAR format (AMI BIOS)

E. Baseline Comparison

chipsec_main -i -n -m tools.uefi.scan_image -a check <baseline.json> <firmware.bin>

• Compare firmware against known-good baseline
• Detect unauthorized modifications

4. Command Flags Reference

5. Output Interpretation

Exit Codes:

Result States:

• PASSED: No issues detected
• WARNING: Potential issue found (e.g., blocked binary detected)
• FAILED: Security vulnerability confirmed

6. Workflows

Workflow 1: Standard Firmware Audit

# 1. Generate inventory
chipsec_main -i -n -m tools.uefi.scan_image -a generate inventory.json firmware.bin

# 2. Scan for known threats
chipsec_main -i -n -m tools.uefi.scan_blocked -a firmware.bin

# 3. Decode structure for manual inspection
chipsec_util -i -n uefi decode firmware.bin

Workflow 2: Malware Detection Focus

# Run blocklist scan and capture details
chipsec_main -i -n -m tools.uefi.scan_blocked -a firmware.bin 2>&1 | tee scan_results.txt

# Check for matches
grep -A5 "match\|found" scan_results.txt

Workflow 3: Baseline Comparison (Update Verification)

# Before update - generate baseline
chipsec_main -i -n -m tools.uefi.scan_image -a generate baseline.json firmware_original.bin

# After update - compare
chipsec_main -i -n -m tools.uefi.scan_image -a check baseline.json firmware_updated.bin

Workflow 4: NVRAM Analysis

# Try VSS format first (most common)
chipsec_util -i -n uefi nvram vss firmware.bin

# If that fails, try NVAR (AMI)
chipsec_util -i -n uefi nvram nvar firmware.bin

7. Known Threats Database

Document the threats detected by scan_blocked:

8. Supported Firmware Formats

• .bin - Raw firmware dumps
• .rom - SPI flash dumps
• .fd - UEFI Firmware Descriptors (OVMF, EDK2)
• .cap - UEFI Capsule updates
• .scap - Signed capsule updates

9. Integration with IoTHackBot

With ffind:

# Find firmware files
ffind /path/to/extracted -a

# Analyze found firmware
chipsec_main -i -n -m tools.uefi.scan_blocked -a firmware.bin

With nmap (post-exploitation):

• After dumping firmware from compromised IoT device
• Analyze for implants or backdoors

10. Troubleshooting

Permission Denied on Logs

sudo mkdir -p /usr/lib/python3.13/site-packages/logs
sudo chmod 777 /usr/lib/python3.13/site-packages/logs

Module Not Found

• Verify chipsec installation: pip show chipsec
• Check Python version compatibility

Decode Produces No Output

• File may not be valid UEFI firmware
• Try file firmware.bin and binwalk firmware.bin first

11. Best Practices

1. Always generate inventory first - Creates baseline for future comparison
2. Run blocklist scan on all firmware - Quick check for known threats
3. Save all output - Use output redirection for documentation
4. Verify firmware format - Use file and binwalk before chipsec
5. Cross-reference findings - Use UEFITool for visual confirmation

12. Example Analysis Session

TARGET="Dell-A02.rom"
OUTPUT_DIR="./chipsec-analysis"
mkdir -p "$OUTPUT_DIR"

echo "[+] Generating EFI inventory..."
chipsec_main -i -n -m tools.uefi.scan_image \
  -a generate "$OUTPUT_DIR/efi_inventory.json" "$TARGET"

echo "[+] Scanning for known threats..."
chipsec_main -i -n -m tools.uefi.scan_blocked \
  -a "$TARGET" 2>&1 | tee "$OUTPUT_DIR/threat_scan.txt"

echo "[+] Decoding firmware structure..."
chipsec_util -i -n uefi decode "$TARGET"

echo "[+] Extracting NVRAM..."
chipsec_util -i -n uefi nvram vss "$TARGET" > "$OUTPUT_DIR/nvram.txt" 2>&1

echo "[+] Analysis complete. Results in: $OUTPUT_DIR/"

13. Success Criteria

A successful chipsec static analysis includes:

• EFI inventory JSON generated with module hashes
• Blocklist scan completed (PASSED or WARNING with details)
• Firmware structure decoded and extractable
• NVRAM variables extracted (if present)
• Any security findings documented with:
  • Threat name and description
  • Affected module GUID
  • SHA256 hash of affected binary
  • Reference URL for remediation

Implementation Steps

1. Create skill directory: .claude/skills/chipsec/

2. Write SKILL.md: Following the structure above with:

   • YAML frontmatter (name, description)
   • Tool overview
   • Prerequisites
   • Command reference with examples
   • Workflows for common tasks
   • Troubleshooting section
   • Integration notes

3. Optional: Create WORKFLOWS.md: Extended workflow documentation

   • Detailed step-by-step for complex analyses
   • Multi-firmware comparison workflows
   • Incident response procedures

4. Test the skill:

   • Run against sample firmware (Dell-A02.rom, OVMF, etc.)
   • Verify all commands work with -i -n flags
   • Test troubleshooting steps

5. Update README.md: Add chipsec to the tools list in iothackbot README

Design Decisions

Why Static Analysis Only?

1. Safety: Live system analysis requires kernel drivers and root access
2. Portability: Static analysis works on any firmware dump
3. Scope Clarity: Separate concerns - live analysis deserves its own skill
4. IoT Focus: Firmware dumps from IoT devices are the common use case

Why These Specific Modules?

Excluded Modules (Require Live System)

• common.bios_wp (BIOS write protection)
• common.spi_lock (SPI flash lock)
• common.smm (SMM memory protection)
• common.secureboot.* (Secure Boot checks)
• tools.uefi.reputation (requires VirusTotal API)
• tools.uefi.s3script_modify (requires live S3 access)

Estimated Complexity

• SKILL.md: ~400-500 lines (similar to nmap-scan skill)
• Development Time: 2-3 hours
• Testing Time: 1 hour with sample firmware

Dependencies

• chipsec >= 1.13.x
• Python 3.x
• Write access to chipsec logs directory (one-time fix)

Future Enhancements

1. Custom blocklist support: Allow user-defined threat signatures
2. Report generation: Structured JSON/HTML reports
3. Diff tool integration: Visual comparison of firmware versions
4. UEFITool integration: Cross-reference with GUI tool findings