Malware analysis with Claude Code and idalib

This tutorial demonstrates a simple agentic use of idalib. Claude Code on the Web inspects malware files in its sandbox, taking a plain-language prompt and driving the entire session: installing IDA, writing analysis scripts, running them against a binary, and extracting findings.

New to idalib? See the Overview first.

Prerequisites

• An active IDA Pro license or IDA Home

• Claude Code on the Web, with connected GitHub repository (or another AI coding assistant that can write and run scripts)

• API Key created:

  • via HCLI by using hcli auth key create

  • via Hex-Rays portal

Optional

• Hex-Rays Claude Code skills: pre-built skills that teach Claude to work with idalib

Walkthrough

0. Set up the cloud environment

In Claude Code on the Web, choose your project's repository and add a cloud environment. Configure it with the following settings so that Claude can install IDA and idalib in the cloud sandbox using HCLI:

• Network access: Full

• Environment variables:

HCLI_API_KEY=your-hcli-key

• Setup script:

#!/bin/bash
uv tool install ida-hcli
pip install ida-domain

New cloud environment

1. Get the sample

Prepare some known malware sample. This example uses the Practical Malware Analysis Lab 01-01.dll, a 32-bit Windows PE DLL from the Mandiant capa test files repository.

2. Give Claude Code a prompt

Open Claude Code on the Web and give it a plain-language prompt, for example:

"Install IDA Pro and idalib with HCLI, then download <URL to your malware sample> and demonstrate you can analyze it with idalib, using the script. For reference, use https://ida-domain.docs.hex-rays.com/llms.txt"

3. Review the analysis script

Claude Code writes an idalib script on the fly in response to the prompt. It uses standard IDAPython modules or the Domain API, depending on the prompt, to open the binary, wait for auto-analysis to complete, and extract segments, exports, imports, functions, and strings.

Exemplary script

#!/usr/bin/env python3
"""
Analyze a PE binary with idalib via the ida-domain API.

Reference: https://ida-domain.docs.hex-rays.com/llms.txt

Usage:
    python analyze.py <path-to-binary>
"""

import sys
from ida_domain import Database


def banner(title):
    print()
    print("=" * 70)
    print(title)
    print("=" * 70)


def main(path):
    # Open the target; run auto-analysis, don't write an .idb back out.
    with Database.open(path=path, save_on_close=False) as db:
        md = db.metadata

        banner("FILE METADATA")
        print(f"  Path         : {db.path}")
        print(f"  Format       : {db.format}")
        print(f"  Architecture : {db.architecture}")
        print(f"  Bitness      : {db.bitness}-bit")
        print(f"  Base address : {hex(db.base_address)}")
        print(f"  Address range: {hex(db.minimum_ea)} - {hex(db.maximum_ea)}")
        print(f"  File size    : {db.filesize} bytes")
        print(f"  MD5          : {db.md5}")
        print(f"  SHA256       : {db.sha256}")
        print(f"  CRC32        : {hex(db.crc32)}")

        banner("SEGMENTS")
        for seg in db.segments:
            name = db.segments.get_name(seg)
            size = db.segments.get_size(seg)
            print(f"  {name:<10} {hex(seg.start_ea)}-{hex(seg.end_ea)}  "
                  f"size={size}")

        banner("ENTRY POINTS / EXPORTS")
        entries = list(db.entries.get_all())
        print(f"  {len(entries)} entry point(s)")
        for e in entries:
            ordinal = f"ord {e.ordinal}" if e.ordinal else "-"
            print(f"  {hex(e.address)}  {ordinal:<8}  {e.name}")

        banner("FUNCTIONS")
        funcs = list(db.functions.get_all())
        print(f"  {len(funcs)} function(s) recovered")
        for f in funcs:
            name = db.functions.get_name(f)
            size = f.end_ea - f.start_ea
            print(f"  {hex(f.start_ea)}  size={size:<5}  {name}")

        banner("IMPORTS (by module)")
        modules = list(db.imports.get_all_modules())
        total_imports = 0
        for mod in modules:
            imps = list(db.imports.get_imports_for_module(mod.index))
            total_imports += len(imps)
            print(f"\n  [{mod.name}] - {len(imps)} import(s)")
            for imp in imps:
                nm = imp.name or f"ordinal_{imp.ordinal}"
                print(f"    {hex(imp.address)}  {nm}")
        print(f"\n  Total: {total_imports} imports across {len(modules)} module(s)")

        banner("STRINGS")
        strings = list(db.strings.get_all())
        print(f"  {len(strings)} string(s) found. Showing all:")
        for s in strings:
            print(f"  {hex(s.address)}  {str(s)!r}")

        banner("ANALYSIS SUMMARY")
        print(f"  {len(funcs)} functions, {total_imports} imports, "
              f"{len(strings)} strings, {len(entries)} entry point(s).")
        # Simple behavioral hint: surface network-related imports.
        net_apis = {"socket", "WSAStartup", "connect", "send", "recv",
                    "gethostbyname", "InternetOpen", "InternetConnect",
                    "CreateProcess", "CreateService", "sleep", "Sleep"}
        seen = []
        for imp in db.imports.get_all_imports():
            if imp.name and imp.name in net_apis:
                seen.append(imp.name)
        if seen:
            print(f"  Notable APIs: {', '.join(sorted(set(seen)))}")


if __name__ == "__main__":
    if len(sys.argv) != 2:
        print(f"usage: {sys.argv[0]} <binary>", file=sys.stderr)
        sys.exit(2)
    main(sys.argv[1])

4. Run the analysis and review the output

Claude Code runs the script directly against the sample and produces the output.

Exemplary output

======================================================================
FILE METADATA
======================================================================
  Path         : /root/malware-analysis/Lab01-01.dll
  Format       : Portable executable for 80386 (PE)
  Architecture : metapc
  Bitness      : 32-bit
  Base address : 0x10000000
  Address range: 0x10001000 - 0x10027000
  File size    : 163840 bytes
  MD5          : 290934c61de9176ad682ffdd65f0a669
  SHA256       : f50e42c8dfaab649bde0398867e930b86c2a599e8db83b8260393082268f2dba
  CRC32        : 0xc414045d

======================================================================
SEGMENTS
======================================================================
  .text      0x10001000-0x10002000  size=4096
  .idata     0x10002000-0x1000205c  size=92
  .rdata     0x1000205c-0x10026000  size=147364
  .data      0x10026000-0x10027000  size=4096

======================================================================
ENTRY POINTS / EXPORTS
======================================================================
  1 entry point(s)
  0x100012fa  ord 268440314  DllEntryPoint

======================================================================
FUNCTIONS
======================================================================
  8 function(s) recovered
  0x10001000  size=13     sub_10001000
  0x10001010  size=490    _DllMain@12
  0x10001200  size=6      sub_10001200
  0x10001210  size=6      sub_10001210
  0x10001220  size=47     __alloca_probe
  0x1000124f  size=171    __CRT_INIT@12
  0x100012fa  size=157    DllEntryPoint
  0x10001398  size=6      _initterm

======================================================================
IMPORTS (by module)
======================================================================

  [KERNEL32] - 5 import(s)
    0x10002000  Sleep
    0x10002004  CreateProcessA
    0x10002008  CreateMutexA
    0x1000200c  OpenMutexA
    0x10002010  CloseHandle

  [WS2_32] - 10 import(s)
    0x1000204c  closesocket
    0x1000203c  connect
    0x10002054  htons
    0x10002038  inet_addr
    0x10002048  recv
    0x10002040  send
    0x10002044  shutdown
    0x10002030  socket
    0x10002034  WSAStartup
    0x10002050  WSACleanup

  [MSVCRT] - 5 import(s)
    0x10002018  _adjust_fdiv
    0x1000201c  malloc
    0x10002020  _initterm
    0x10002024  free
    0x10002028  strncmp

  Total: 20 imports across 3 module(s)

======================================================================
STRINGS
======================================================================
  16 string(s) found. Showing all:
  0x1000210a  'CloseHandle'
  0x10002118  'Sleep'
  0x10002120  'CreateProcessA'
  0x10002132  'CreateMutexA'
  0x10002142  'OpenMutexA'
  0x1000214e  'KERNEL32.dll'
  0x1000215c  'WS2_32.dll'
  0x1000216a  'strncmp'
  0x10002172  'MSVCRT.dll'
  0x10002188  '_initterm'
  0x10002194  'malloc'
  0x1000219e  '_adjust_fdiv'
  0x10026018  'sleep'
  0x10026020  'hello'
  0x10026028  '127.26.152.13'
  0x10026038  'SADFHUHF'

======================================================================
ANALYSIS SUMMARY
======================================================================
  8 functions, 20 imports, 16 strings, 1 entry point(s).
  Notable APIs: Sleep, WSAStartup, connect, recv, send, socket

What this reveals

In this example, the strings and imports tell the story: 127.26.152.13 is a hardcoded C2 IP, SADFHUHF is a mutex name used to prevent re-infection, and the WS2_32 imports confirm raw TCP socket communication. This is a classic backdoor from the Practical Malware Analysis lab series.

What's next

For a broader look at the available approaches, see Agentic IDA with idalib.