ByteRay MCP -- Binary Analysis Skill

SSA-First Rule

When tracing data flow, always use SSA form tools. SSA uniquely versions every variable assignment (buf#1, buf#2), making it precise for tracking where data flows. Use these tools for tracing:

• trace_ssa_step -- Incremental SSA trace, 5 steps at a time. Preferred for interactive analysis.
• trace_variable -- Full-function SSA variable scan. Use when you need all uses at once.
• read_ssa_form -- View all SSA instructions. Use when you need the complete SSA listing.

Do NOT use read_pseudocode for data flow analysis -- pseudocode merges variable versions and loses precision.

Vulnerability Reporting Rules (CRITICAL)

Never make absolute exploitability claims

• NEVER say "this is not exploitable", "this cannot be exploited", or "this is a false positive"
• NEVER say "this is definitely exploitable" without taint evidence
• Binary analysis operates on incomplete information -- you cannot see runtime state, environment, or inputs
• Frame ALL findings in terms of severity and confidence, not binary exploitable/not-exploitable

CVSS 4.0 severity is mandatory

Every finding MUST include a CVSS 4.0 severity assessment:

• Severity: Critical / High / Medium / Low (based on CVSS 4.0 base score)
• CVSS 4.0 Vector: e.g. CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:H/VI:H/VA:H
• CWE: The most specific applicable CWE ID
• Confidence: High / Medium / Low (see below)

Taint analysis determines confidence

• High confidence: trace_data_flow or trace_ssa_step confirms a complete source-to-sink path with no sanitization detected by check_sanitization
• Medium confidence: Pseudocode shows a likely path, but taint analysis was inconclusive or not yet run; OR taint confirms a path but check_sanitization found partial mitigation
• Low confidence: Finding based only on dangerous function presence (e.g. strcpy in imports) without data flow evidence

You MUST run taint analysis tools (trace_data_flow, trace_ssa_step) before assigning High confidence. Do NOT rely on read_pseudocode or list_imports alone -- these show structure, not data flow.

Sanitization adjusts severity, never dismisses

If check_sanitization detects mitigation:

• Reduce severity by one level (e.g. High -> Medium)
• Note the sanitization in the report
• NEVER dismiss the finding entirely -- sanitization can be incomplete or bypassable

Address Format (CRITICAL)

All address parameters MUST be integers, not strings. The server rejects null.

• Correct: address=4196352 or address=0x401000
• Wrong: address="0x401000" or address=null

When you get an address from a tool output (e.g. "address": "0x401000"), parse the hex string to an integer before passing it to the next tool.

File Upload (MANDATORY for files uploaded through Claude web)

The ByteRay MCP server runs remotely. It CANNOT access paths like /mnt/user-data/uploads/... -- those only exist in Claude's sandbox. Do NOT call open_binary with a sandbox path. It will always fail with "File not found."

Choose the upload method based on the situation:

Recommended: URL-based download (fastest, any size)

If the user can provide a URL to the binary (GitHub release, S3, Google Drive direct link, any public HTTP URL):

1. fetch_binary(url="https://example.com/firmware.bin", filename="firmware.bin") -- server downloads directly, returns {path, size, sha256}
2. open_binary(path=returned_path) -- begins analysis

This is instant regardless of file size because the server fetches the binary directly over HTTP -- no base64 encoding, no token limits.

Small binaries (under ~20KB, no URL available)

1. Use the Analysis tool to read and encode the file:

import base64
with open("/mnt/user-data/uploads/filename", "rb") as f:
    b64 = base64.b64encode(f.read()).decode()
print(len(b64))  # verify it encoded

2. Call open_binary(path="filename", content_base64=b64) with the encoded string.

Large binaries (over ~20KB, no URL available) -- Chunked Upload

For larger files without a URL, the base64 string is too large for a single tool call. Use chunked upload:

1. Use the Analysis tool to read, encode, and split into chunks:

import base64, math, os

with open("/mnt/user-data/uploads/filename", "rb") as f:
    b64 = base64.b64encode(f.read()).decode()

CHUNK_SIZE = 8192  # 8KB per chunk
total_chunks = math.ceil(len(b64) / CHUNK_SIZE)
for i in range(total_chunks):
    chunk = b64[i * CHUNK_SIZE : (i + 1) * CHUNK_SIZE]
    with open(f"/tmp/chunk_{i}.txt", "w") as cf:
        cf.write(chunk)
print(f"Split into {total_chunks} chunks")

2. start_upload(filename="name", total_chunks=N) -- returns upload_id
3. For each chunk (0 to N-1), read the chunk file with Analysis, then: upload_chunk(upload_id=id, chunk_index=i, data=chunk_data)
4. finalize_upload(upload_id=id) -- returns {path, size, sha256}
5. open_binary(path=returned_path) -- begins analysis

Performance note: Base64 transfer adds ~33% overhead. For binaries already on the server, always use the local path instead. Always prefer fetch_binary with a URL when possible.

Core Workflow: Always Start Here

1. Open the binary (see upload section above if file was uploaded)
   • Uploaded file: encode with Analysis tool, then open_binary(path="filename", content_base64=b64)
   • Server-local file: open_binary(path="/absolute/path/to/binary")
2. Read triage: arch, platform, language, security flags, firmware type
3. find_attack_surface(session_id) -- returns sources, sinks, suggestions
4. Follow suggestions or investigate manually using patterns below

Address Resolution

When you have a name and need an address:

• resolve_name(session_id, name="system") -- returns all matching addresses
• Then use the address with goto_address, read_pseudocode, who_calls, etc.

When you have an address and need context + code:

• goto_address(session_id, address=0x401234) -- shows section, function, symbol, AND code
• inspect_address(session_id, address) -- metadata only (no code, faster)

Vulnerability Hunting Patterns

Incremental SSA Trace (preferred for interactive analysis)

1. find_attack_surface -- identify a sink (e.g. "system")
2. who_calls(function_name="system") -- get caller address
3. trace_ssa_step(address, variable_name="buf", direction="backward", max_steps=5) -- see 5 operations leading to the sink argument
4. If has_more: trace_ssa_step(..., from_index=N, max_steps=5) -- next 5 operations
5. If reached_source: vulnerability confirmed (tainted data reaches sink)
6. At any suspicious step: check_sanitization(address) -- is this a safe pattern?

Source-to-Sink Trace (automated, single function)

1. find_attack_surface -- identify sources (recv, fgets) and sinks (system, strcpy)
2. who_calls(function_name="system") -- find functions calling the dangerous sink
3. For each caller: read_pseudocode(address) -- does user input flow to the sink?
4. trace_data_flow(function_address) -- run taint analysis to confirm the path
5. If taint confirmed: report with CVSS 4.0 severity, CWE, confidence level, source-to-sink chain, and mitigation suggestions (see Vulnerability Reporting Rules)

Sanitization Check Pattern

1. trace_ssa_step finds a suspicious path: recv -> buf -> system
2. Between recv and system, trace_ssa_step shows an if-block or function call
3. check_sanitization(if_block_address) -- reports what sanitization was detected
4. If is_sanitized=true: path is likely safe, not vulnerable
5. If is_sanitized=false: no protection found, vulnerability confirmed

CFG Navigation Pattern

1. navigate_cfg(address, direction="forward") -- see where execution goes after this block
2. navigate_cfg(successor_address, direction="forward") -- step further along the path
3. navigate_cfg(address, direction="backward") -- see where execution came from
4. Use with view="ssa" for data flow precision or view="pseudocode" for readability

Reachability Check

1. resolve_name("target_function") -- get address
2. get_call_tree(address, direction="callers", depth=3) -- who can reach it?
3. For each path: read_pseudocode at each level to check for sanitization

Navigating Large Binaries

1. list_functions(filter="handler") -- narrow down interesting functions
2. get_function_detail(address) -- see signature, stack frame, calling convention
3. read_block(address) -- show code for just one block (not the entire function)
4. navigate_cfg(address, direction="forward") -- step through blocks one at a time

Import-Driven Analysis

1. list_imports -- see what external APIs the binary links
2. For each dangerous import: who_calls(function_name="strcpy")
3. Examine each caller with read_pseudocode or read_block

Tool Selection Guide

Question	Tool
What is at address X?	goto_address (code + context) or inspect_address (metadata)
Where is function Y?	resolve_name
Show the code	read_pseudocode (whole function) or read_block (single block)
Who calls this?	who_calls (1 level) or get_call_tree(direction="callers") (N levels)
What does this call?	what_calls (1 level) or get_call_tree(direction="callees") (N levels)
Is there a vulnerability?	trace_ssa_step (incremental, interactive) or trace_data_flow (automated, single function)
Is data sanitized?	check_sanitization(address)
Walk the CFG step by step	navigate_cfg(address, direction)
What APIs does it use?	list_imports
Show strings	get_strings(filter="password") or search_strings
What sections/segments?	list_sections, list_segments
Find byte pattern	search_bytes(pattern="48 8b 05")
Trace a variable (full)	trace_variable(address, variable_name)
Trace a variable (step)	trace_ssa_step(address, variable_name, direction, max_steps)
See SSA form	read_ssa_form(address)
See assembly	read_assembly(address)
Read raw bytes	read_memory(address, length)
Control flow graph	get_control_flow(address, format="mermaid")
File hashes	get_file_hash(session_id)

Performance Tips

• Prefer read_block over read_pseudocode for large functions. read_pseudocode returns the entire function which can be thousands of lines. read_block returns a single basic block -- much faster and smaller.
• Use pagination on list_functions and get_strings. Set limit=50 instead of loading all 200 results if you only need a few.
• check_sanitization requires a function address. Do NOT call it on PLT stubs, thunks, or data addresses. If you get "No function at 0x...", use inspect_address or goto_address first to find the containing function's start address, then retry.
• Batch your analysis. After find_attack_surface, plan which functions to examine before making individual tool calls. This reduces round trips.

Error Recovery

• "No function at 0x...": The address is not inside a recognized function (likely a PLT stub or data section). Use goto_address to find the nearest function, then use that function's start address instead.
• "Session not found": The session expired or was never created. Call open_binary again to create a new session.
• Deserialization error: You likely sent a string or null for an address parameter. Re-send with an integer value.

Tips

• Addresses from tool outputs (e.g. function addresses from list_functions) can be passed directly to other tools
• Use trace_ssa_step instead of trace_data_flow for interactive analysis -- it returns 5 steps at a time and you decide whether to continue
• Use check_sanitization whenever trace_ssa_step shows a conditional branch or function call between source and sink
• Use navigate_cfg with view="ssa" for the most precise data flow during CFG walking
• Use read_block instead of read_pseudocode when a function has many blocks and you only need to see a specific area
• get_call_tree is limited to depth 5 and 200 nodes for performance
• trace_data_flow works on a single function; chain with who_calls / get_call_tree for interprocedural analysis
• For firmware (VxWorks, UEFI), find_attack_surface detects firmware-specific sources/sinks automatically

Complete Tool List (42 tools)

For full parameter details, see tool-reference.md.