From 73d160aa38a3fdaa762ba69af939f149f65dd800 Mon Sep 17 00:00:00 2001 From: Noor Fatima Date: Sat, 26 Sep 2026 23:07:34 +0500 Subject: [PATCH 1/5] feat(skills): add CyberChef MCP tooling skill and documentation --- docs/integrations/mcp.mdx | 7 ++ strix/skills/tooling/cyberchef.md | 105 ++++++++++++++++++++++++++++++ 2 files changed, 112 insertions(+) create mode 100644 strix/skills/tooling/cyberchef.md diff --git a/docs/integrations/mcp.mdx b/docs/integrations/mcp.mdx index 6b9945c9..a8068883 100644 --- a/docs/integrations/mcp.mdx +++ b/docs/integrations/mcp.mdx @@ -26,6 +26,13 @@ Paste the servers you want into `~/.strix/mcp-servers.json`. The example below s ```json [ + { + "name": "cyberchef", + "transport": "stdio", + "command": "npx", + "args": ["-y", "cyberchef-mcp"], + "notes": "CyberChef MCP server for multi-layer payload deobfuscation, crypto decoding, and entropy analysis." + }, { "name": "local_fs", "transport": "stdio", diff --git a/strix/skills/tooling/cyberchef.md b/strix/skills/tooling/cyberchef.md new file mode 100644 index 00000000..f07ca47b --- /dev/null +++ b/strix/skills/tooling/cyberchef.md @@ -0,0 +1,105 @@ +--- +name: cyberchef +description: Multi-layer payload deobfuscation, cryptographic decoding, heuristic recipe detection (magic), and entropy analysis via CyberChef MCP. +--- + +# CyberChef MCP Tooling Playbook + +Official resources: +- https://github.com/gchq/CyberChef +- https://github.com/noor202401938-netizen/cyber-chef-mcp +- https://gchq.github.io/CyberChef/ +- https://modelcontextprotocol.io + +CyberChef provides over 500 data transformation and cryptographic operations. Connected via the Model Context Protocol (MCP) server `cyberchef`, it enables Strix agents to autonomously analyze, deobfuscate, unpack, and verify encoded exploit payloads, authorization tokens, and obfuscated attack vectors without manual intervention or guessing. + +## Canonical MCP Tool Names & Signatures + +When the `cyberchef` MCP connection is active, the following tools are available in the agent registry: + +- `cyberchef_magic(input: string)`: Run heuristic detection across known encodings, ciphers, and hash formats. Returns recommended deobfuscation recipes and confidence scores. +- `cyberchef_bake(input: string, recipe: [{ op: string, args?: any[] }])`: Execute sequential operation chains (e.g. `[{"op": "From Base64"}, {"op": "URL Decode"}]`). +- `cyberchef_from_base64(input: string, urlSafe?: boolean)`: Decode standard or URL-safe Base64 strings. +- `cyberchef_to_base64(input: string, urlSafe?: boolean)`: Encode plaintext into Base64 / URL-safe Base64. +- `cyberchef_from_hex(input: string, delimiter?: "None"|"Space"|"0x"|"Comma")`: Convert hexadecimal sequences to text. +- `cyberchef_url_decode(input: string)`: Decode single or multi-round percent-encoded parameters. +- `cyberchef_rot13(input: string, amount?: number)`: Rotate characters by offset (default 13, Caesar cipher support). +- `cyberchef_xor(input: string, key: string, keyFormat?: "UTF8"|"Hex")`: Decrypt or apply bitwise XOR with secret key. +- `cyberchef_jwt_decode(token: string)`: Parse and inspect header, claims, alg, and signatures of JSON Web Tokens. +- `cyberchef_entropy(input: string)`: Calculate Shannon entropy (0.0 to 8.0) to distinguish plaintext, compressed data, and encrypted or packed payloads. +- `cyberchef_defang_url(url: string)`: Defang malicious or suspicious indicators (`hxxps://target[.]com`) for safe reporting. +- `cyberchef_extract_entities(text: string)`: Extract URLs, IP addresses, and email addresses from raw logs or memory strings. + +## Agent-Safe Baseline for Automation + +1. **Heuristic First**: + Always run `cyberchef_magic` on unknown high-entropy or encoded strings before guessing transformations: + ```json + { + "tool": "cyberchef_magic", + "arguments": { "input": "ZXlKaGJHY2lPaUpTVXpVbkxh..." } + } + ``` + +2. **Sequential Multi-Layer Deobfuscation (Bake)**: + For payloads with layered obfuscation (e.g. Hex inside Base64 inside URL-encoded query params): + ```json + { + "tool": "cyberchef_bake", + "arguments": { + "input": "%34%38%36%35%36%63%36%63%36%66", + "recipe": [ + { "op": "URL Decode" }, + { "op": "From Hex", "args": ["None"] } + ] + } + } + ``` + +3. **High-Entropy Verification**: + Before analyzing suspicious parameters, assess randomness and encryption depth: + ```json + { + "tool": "cyberchef_entropy", + "arguments": { "input": "01a2fe89cb994821a0d8e4..." } + } + ``` + - **Entropy < 4.0**: Plain English text, uncompressed source code, or structured JSON/XML. + - **Entropy 4.0 - 6.5**: Encoded payloads (Base64, Hex) or compressed data. + - **Entropy > 7.0**: Strong encryption, cryptographic hashes, or packed binary shellcode. + +## Common Security Analysis Patterns + +### Pattern 1: Nested WAF Bypass / Obfuscated Injection Vector +When target web applications accept encoded input in parameters or cookies: +1. Extract candidate parameter from HTTP request or response. +2. Call `cyberchef_magic` to determine layers. +3. Call `cyberchef_bake` with the suggested pipeline to recover the plaintext injection string. +4. Verify whether the underlying query contains unsanitized SQLi (`UNION SELECT`), XSS, or SSRF vectors. + +### Pattern 2: JWT Security Inspection +When encountering `Authorization: Bearer ` or session tokens: +1. Call `cyberchef_jwt_decode(token)`. +2. Inspect the header: check for `alg: "none"`, `alg: "HS256"` with potential asymmetric public key confusion, or empty signatures. +3. Inspect claims: verify expiry timestamps (`exp`), issuer (`iss`), role/privilege elevations, and user identities. + +### Pattern 3: XOR Obfuscation Recovery +When inspecting hardcoded binary strings, PowerShell scripts, or obfuscated malware droppers: +1. Identify probable key length or common plaintext prefix (e.g., `MZ`, `http`, `function`). +2. Run `cyberchef_xor` iterating candidate keys to extract underlying C2 endpoints or script payloads. + +## Critical Correctness Rules + +- **Do Not Guess Encodings**: If a string contains `=, %, 0x` or unexpected symbols, run `cyberchef_magic` first rather than blindly applying base64 or URL decoding. +- **Preserve Raw Inputs**: Keep the original obfuscated string in agent memory/notes alongside the decoded output for accurate proof-of-concept (PoC) reporting. +- **Fail-Safe Fallback**: If an operation fails during `cyberchef_bake`, isolate the failing recipe step and execute individual tools (`cyberchef_from_base64`, `cyberchef_url_decode`) sequentially. +- **Safe Defanging**: Always run `cyberchef_defang_url` on confirmed malicious or C2 URLs before writing final markdown reports. + +## Failure Recovery + +- If `cyberchef_from_base64` throws a padding error, retry with `urlSafe: true` or inspect whether characters are URL percent-encoded first. +- If `cyberchef_from_hex` produces unprintable garbage characters, check if the input is big-endian or uses custom delimiters (`0x`, `Space`, `,`). +- If `cyberchef_bake` returns an error, use `cyberchef_help(query: "")` to verify supported operation names and argument formats. + +If uncertain, query web_search with: +`site:gchq.github.io/CyberChef cyberchef ` From 9c64d2711187a8fa209218c23c173d8e7b39a10b Mon Sep 17 00:00:00 2001 From: Noor Fatima Date: Sat, 26 Sep 2026 23:28:59 +0500 Subject: [PATCH 2/5] docs: update cyberchef mcp package to @noorfatima123456/cyber-chef-mcp --- docs/integrations/mcp.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/integrations/mcp.mdx b/docs/integrations/mcp.mdx index a8068883..01b7e75e 100644 --- a/docs/integrations/mcp.mdx +++ b/docs/integrations/mcp.mdx @@ -30,7 +30,7 @@ Paste the servers you want into `~/.strix/mcp-servers.json`. The example below s "name": "cyberchef", "transport": "stdio", "command": "npx", - "args": ["-y", "cyberchef-mcp"], + "args": ["-y", "@noorfatima123456/cyber-chef-mcp"], "notes": "CyberChef MCP server for multi-layer payload deobfuscation, crypto decoding, and entropy analysis." }, { From b851572dac349b6b5c0ed9afe0e154116a824b42 Mon Sep 17 00:00:00 2001 From: Noor Fatima Date: Sat, 26 Sep 2026 23:38:21 +0500 Subject: [PATCH 3/5] fix(skills): use call_mcp dispatch interface, calibrate entropy thresholds, and align docs --- docs/integrations/mcp.mdx | 2 +- strix/skills/tooling/cyberchef.md | 148 +++++++++++++++++++----------- 2 files changed, 94 insertions(+), 56 deletions(-) diff --git a/docs/integrations/mcp.mdx b/docs/integrations/mcp.mdx index 01b7e75e..35f069a4 100644 --- a/docs/integrations/mcp.mdx +++ b/docs/integrations/mcp.mdx @@ -22,7 +22,7 @@ Create the directory if it does not exist, then write the file: mkdir -p ~/.strix ``` -Paste the servers you want into `~/.strix/mcp-servers.json`. The example below shows one of each transport: a local filesystem server over `stdio` and a remote GitHub server over `http` with a bearer token: +Paste the servers you want into `~/.strix/mcp-servers.json`. The example below shows local `stdio` servers (CyberChef for payload deobfuscation and a local filesystem server) alongside a remote GitHub server over `http` with a bearer token: ```json [ diff --git a/strix/skills/tooling/cyberchef.md b/strix/skills/tooling/cyberchef.md index f07ca47b..f64c2fdb 100644 --- a/strix/skills/tooling/cyberchef.md +++ b/strix/skills/tooling/cyberchef.md @@ -13,93 +13,131 @@ Official resources: CyberChef provides over 500 data transformation and cryptographic operations. Connected via the Model Context Protocol (MCP) server `cyberchef`, it enables Strix agents to autonomously analyze, deobfuscate, unpack, and verify encoded exploit payloads, authorization tokens, and obfuscated attack vectors without manual intervention or guessing. -## Canonical MCP Tool Names & Signatures +## MCP Discovery & Dispatch Workflow -When the `cyberchef` MCP connection is active, the following tools are available in the agent registry: +In Strix, agents interact with external MCP servers through the standard generic-dispatch tools: +1. **Discover Connection**: Call `list_mcps()` to verify that the `cyberchef` connection is active. +2. **Search Tools**: Call `search_mcp_tools(connection="cyberchef", query="magic")` to locate matching tool names. +3. **Inspect Schema**: Call `get_mcp_tool_schema(connection="cyberchef", tool="cyberchef_magic")` to review argument parameters. +4. **Dispatch Call**: Call `call_mcp(connection="cyberchef", tool="", arguments={...})` to execute the operation. -- `cyberchef_magic(input: string)`: Run heuristic detection across known encodings, ciphers, and hash formats. Returns recommended deobfuscation recipes and confidence scores. -- `cyberchef_bake(input: string, recipe: [{ op: string, args?: any[] }])`: Execute sequential operation chains (e.g. `[{"op": "From Base64"}, {"op": "URL Decode"}]`). -- `cyberchef_from_base64(input: string, urlSafe?: boolean)`: Decode standard or URL-safe Base64 strings. -- `cyberchef_to_base64(input: string, urlSafe?: boolean)`: Encode plaintext into Base64 / URL-safe Base64. -- `cyberchef_from_hex(input: string, delimiter?: "None"|"Space"|"0x"|"Comma")`: Convert hexadecimal sequences to text. -- `cyberchef_url_decode(input: string)`: Decode single or multi-round percent-encoded parameters. -- `cyberchef_rot13(input: string, amount?: number)`: Rotate characters by offset (default 13, Caesar cipher support). -- `cyberchef_xor(input: string, key: string, keyFormat?: "UTF8"|"Hex")`: Decrypt or apply bitwise XOR with secret key. -- `cyberchef_jwt_decode(token: string)`: Parse and inspect header, claims, alg, and signatures of JSON Web Tokens. -- `cyberchef_entropy(input: string)`: Calculate Shannon entropy (0.0 to 8.0) to distinguish plaintext, compressed data, and encrypted or packed payloads. -- `cyberchef_defang_url(url: string)`: Defang malicious or suspicious indicators (`hxxps://target[.]com`) for safe reporting. -- `cyberchef_extract_entities(text: string)`: Extract URLs, IP addresses, and email addresses from raw logs or memory strings. +## High-Signal CyberChef Tools + +When connected to `cyberchef`, the following tools are available on the connection: + +- `cyberchef_magic`: Run heuristic detection across known encodings, ciphers, and hash formats. Returns recommended deobfuscation recipes and confidence scores. +- `cyberchef_bake`: Execute sequential operation chains (e.g. `[{"op": "From Base64"}, {"op": "URL Decode"}]`). +- `cyberchef_from_base64`: Decode standard or URL-safe Base64 strings. +- `cyberchef_to_base64`: Encode plaintext into Base64 / URL-safe Base64. +- `cyberchef_from_hex`: Convert hexadecimal sequences to text (supports `None`, `Space`, `0x`, `Comma` delimiters). +- `cyberchef_url_decode`: Decode single or multi-round percent-encoded parameters. +- `cyberchef_rot13`: Rotate characters by offset (default 13, Caesar cipher support). +- `cyberchef_xor`: Decrypt or apply bitwise XOR with secret key. +- `cyberchef_jwt_decode`: Parse and inspect header, claims, alg, and signatures of JSON Web Tokens. +- `cyberchef_entropy`: Calculate Shannon entropy to distinguish plaintext, compressed data, and encrypted or packed payloads. +- `cyberchef_defang_url`: Defang malicious or suspicious indicators (`hxxps://target[.]com`) for safe reporting. +- `cyberchef_extract_entities`: Extract URLs, IP addresses, and email addresses from raw logs or memory strings. ## Agent-Safe Baseline for Automation -1. **Heuristic First**: - Always run `cyberchef_magic` on unknown high-entropy or encoded strings before guessing transformations: - ```json - { - "tool": "cyberchef_magic", - "arguments": { "input": "ZXlKaGJHY2lPaUpTVXpVbkxh..." } - } - ``` +### 1. Heuristic First (`cyberchef_magic`) +Always run `cyberchef_magic` via `call_mcp` on unknown high-entropy or encoded strings before guessing transformations: +```json +{ + "tool": "call_mcp", + "arguments": { + "connection": "cyberchef", + "tool": "cyberchef_magic", + "arguments": { + "input": "ZXlKaGJHY2lPaUpTVXpVbkxh..." + } + } +} +``` -2. **Sequential Multi-Layer Deobfuscation (Bake)**: - For payloads with layered obfuscation (e.g. Hex inside Base64 inside URL-encoded query params): - ```json - { - "tool": "cyberchef_bake", - "arguments": { - "input": "%34%38%36%35%36%63%36%63%36%66", - "recipe": [ - { "op": "URL Decode" }, - { "op": "From Hex", "args": ["None"] } - ] - } - } - ``` +### 2. Sequential Multi-Layer Deobfuscation (`cyberchef_bake`) +For payloads with layered obfuscation (e.g. Hex inside Base64 inside URL-encoded query params): +```json +{ + "tool": "call_mcp", + "arguments": { + "connection": "cyberchef", + "tool": "cyberchef_bake", + "arguments": { + "input": "%34%38%36%35%36%63%36%63%36%66", + "recipe": [ + { "op": "URL Decode" }, + { "op": "From Hex", "args": ["None"] } + ] + } + } +} +``` -3. **High-Entropy Verification**: - Before analyzing suspicious parameters, assess randomness and encryption depth: - ```json - { - "tool": "cyberchef_entropy", - "arguments": { "input": "01a2fe89cb994821a0d8e4..." } - } - ``` - - **Entropy < 4.0**: Plain English text, uncompressed source code, or structured JSON/XML. - - **Entropy 4.0 - 6.5**: Encoded payloads (Base64, Hex) or compressed data. - - **Entropy > 7.0**: Strong encryption, cryptographic hashes, or packed binary shellcode. +### 3. Entropy Assessment & Encoding Representation Calibration +When evaluating whether a payload or parameter is encrypted, packed shellcode, or benign text, evaluate Shannon entropy through `call_mcp`: +```json +{ + "tool": "call_mcp", + "arguments": { + "connection": "cyberchef", + "tool": "cyberchef_entropy", + "arguments": { + "input": "01a2fe89cb994821a0d8e4..." + } + } +} +``` + +> [!IMPORTANT] +> **Calibrate entropy thresholds by input encoding representation:** +> Shannon entropy measures bits of information per character. The theoretical maximum is strictly bounded by the alphabet size ($\log_2(N)$): +> - **Hex Strings (16 characters, max 4.0 bits/char)**: +> - *Plain text / formatted Hex*: ~2.5 – 3.2 +> - *High-entropy ciphertext / encrypted payload*: **3.8 – 4.0** (Cannot exceed 4.0!) +> - *Warning*: Do not misclassify hex ciphertext scoring ~3.9 as low-entropy content. +> - **Base64 Strings (64 characters, max 6.0 bits/char)**: +> - *Plain text Base64*: ~3.8 – 4.5 +> - *High-entropy ciphertext / packed data*: **5.7 – 6.0** (Cannot exceed 6.0!) +> - **Raw Binary / Decoded Byte Streams (256 values, max 8.0 bits/byte)**: +> - *Plain text / uncompressed source code*: < 4.5 +> - *Compressed archives / packed code / encrypted shellcode*: > 7.2 +> +> **Best Practice**: Decode encoded representations (Hex, Base64) to raw bytes via `cyberchef_from_hex` or `cyberchef_from_base64` before evaluating raw Shannon entropy. ## Common Security Analysis Patterns ### Pattern 1: Nested WAF Bypass / Obfuscated Injection Vector When target web applications accept encoded input in parameters or cookies: 1. Extract candidate parameter from HTTP request or response. -2. Call `cyberchef_magic` to determine layers. -3. Call `cyberchef_bake` with the suggested pipeline to recover the plaintext injection string. +2. Call `call_mcp(connection="cyberchef", tool="cyberchef_magic", arguments={"input": candidate})` to determine layers. +3. Call `call_mcp(connection="cyberchef", tool="cyberchef_bake", arguments={"input": candidate, "recipe": [...]})` with the suggested pipeline to recover the plaintext injection string. 4. Verify whether the underlying query contains unsanitized SQLi (`UNION SELECT`), XSS, or SSRF vectors. ### Pattern 2: JWT Security Inspection When encountering `Authorization: Bearer ` or session tokens: -1. Call `cyberchef_jwt_decode(token)`. +1. Call `call_mcp(connection="cyberchef", tool="cyberchef_jwt_decode", arguments={"token": token})`. 2. Inspect the header: check for `alg: "none"`, `alg: "HS256"` with potential asymmetric public key confusion, or empty signatures. 3. Inspect claims: verify expiry timestamps (`exp`), issuer (`iss`), role/privilege elevations, and user identities. ### Pattern 3: XOR Obfuscation Recovery When inspecting hardcoded binary strings, PowerShell scripts, or obfuscated malware droppers: 1. Identify probable key length or common plaintext prefix (e.g., `MZ`, `http`, `function`). -2. Run `cyberchef_xor` iterating candidate keys to extract underlying C2 endpoints or script payloads. +2. Run `call_mcp(connection="cyberchef", tool="cyberchef_xor", arguments={"input": data, "key": candidate_key})` iterating candidate keys to extract underlying C2 endpoints or script payloads. ## Critical Correctness Rules +- **Use `call_mcp` Dispatch**: Never attempt to call CyberChef tools directly as top-level agent tools. Always dispatch through `call_mcp(connection="cyberchef", tool="...", arguments={...})`. - **Do Not Guess Encodings**: If a string contains `=, %, 0x` or unexpected symbols, run `cyberchef_magic` first rather than blindly applying base64 or URL decoding. - **Preserve Raw Inputs**: Keep the original obfuscated string in agent memory/notes alongside the decoded output for accurate proof-of-concept (PoC) reporting. -- **Fail-Safe Fallback**: If an operation fails during `cyberchef_bake`, isolate the failing recipe step and execute individual tools (`cyberchef_from_base64`, `cyberchef_url_decode`) sequentially. -- **Safe Defanging**: Always run `cyberchef_defang_url` on confirmed malicious or C2 URLs before writing final markdown reports. +- **Fail-Safe Fallback**: If an operation fails during `cyberchef_bake`, isolate the failing recipe step and execute individual tools (`cyberchef_from_base64`, `cyberchef_url_decode`) sequentially via `call_mcp`. +- **Safe Defanging**: Always run `cyberchef_defang_url` via `call_mcp` on confirmed malicious or C2 URLs before writing final markdown reports. ## Failure Recovery - If `cyberchef_from_base64` throws a padding error, retry with `urlSafe: true` or inspect whether characters are URL percent-encoded first. -- If `cyberchef_from_hex` produces unprintable garbage characters, check if the input is big-endian or uses custom delimiters (`0x`, `Space`, `,`). -- If `cyberchef_bake` returns an error, use `cyberchef_help(query: "")` to verify supported operation names and argument formats. +- If `cyberchef_from_hex` produces unprintable characters, check if the input is big-endian or uses custom delimiters (`0x`, `Space`, `,`). +- If `call_mcp` returns an unknown tool error, call `search_mcp_tools(connection="cyberchef", query="...")` to discover the exact tool names registered by the server. If uncertain, query web_search with: `site:gchq.github.io/CyberChef cyberchef ` From d06cb9ca3b2caa0fe7db4864a783c1e167e059ed Mon Sep 17 00:00:00 2001 From: Noor Fatima Date: Mon, 28 Sep 2026 00:19:25 +0500 Subject: [PATCH 4/5] docs(cyberchef): correct operation count to 28 core deterministic operations --- strix/skills/tooling/cyberchef.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/strix/skills/tooling/cyberchef.md b/strix/skills/tooling/cyberchef.md index f64c2fdb..e2bc0c15 100644 --- a/strix/skills/tooling/cyberchef.md +++ b/strix/skills/tooling/cyberchef.md @@ -11,7 +11,7 @@ Official resources: - https://gchq.github.io/CyberChef/ - https://modelcontextprotocol.io -CyberChef provides over 500 data transformation and cryptographic operations. Connected via the Model Context Protocol (MCP) server `cyberchef`, it enables Strix agents to autonomously analyze, deobfuscate, unpack, and verify encoded exploit payloads, authorization tokens, and obfuscated attack vectors without manual intervention or guessing. +CyberChef MCP provides 28 core data transformation, cryptographic, and forensic operations with zero external dependencies. Connected via the Model Context Protocol (MCP) server `cyberchef`, it enables Strix agents to autonomously analyze, deobfuscate, unpack, and verify encoded exploit payloads, authorization tokens, and obfuscated attack vectors with deterministic sub-millisecond execution. ## MCP Discovery & Dispatch Workflow From 1fb92788db94aa6a9c20cb827ee0ccea4e82037a Mon Sep 17 00:00:00 2001 From: Noor Fatima Date: Tue, 29 Sep 2026 21:18:53 +0500 Subject: [PATCH 5/5] fix(skills): add raw-byte entropy workflow and in-engine bake chaining --- strix/skills/tooling/cyberchef.md | 68 +++++++++++++++++++++++++++---- 1 file changed, 60 insertions(+), 8 deletions(-) diff --git a/strix/skills/tooling/cyberchef.md b/strix/skills/tooling/cyberchef.md index e2bc0c15..d618a161 100644 --- a/strix/skills/tooling/cyberchef.md +++ b/strix/skills/tooling/cyberchef.md @@ -11,7 +11,7 @@ Official resources: - https://gchq.github.io/CyberChef/ - https://modelcontextprotocol.io -CyberChef MCP provides 28 core data transformation, cryptographic, and forensic operations with zero external dependencies. Connected via the Model Context Protocol (MCP) server `cyberchef`, it enables Strix agents to autonomously analyze, deobfuscate, unpack, and verify encoded exploit payloads, authorization tokens, and obfuscated attack vectors with deterministic sub-millisecond execution. +CyberChef MCP provides 33 core data transformation, cryptographic, compression (Gunzip, Gzip, Zlib, Raw Deflate), and forensic operations with zero external dependencies. Connected via the Model Context Protocol (MCP) server `cyberchef`, it enables Strix agents to autonomously analyze, deobfuscate, unpack, and verify encoded exploit payloads, authorization tokens, and obfuscated attack vectors with deterministic sub-millisecond execution. ## MCP Discovery & Dispatch Workflow @@ -74,8 +74,13 @@ For payloads with layered obfuscation (e.g. Hex inside Base64 inside URL-encoded } ``` -### 3. Entropy Assessment & Encoding Representation Calibration -When evaluating whether a payload or parameter is encrypted, packed shellcode, or benign text, evaluate Shannon entropy through `call_mcp`: +### 3. Entropy Assessment & Raw-Byte Workflow +When evaluating whether a payload or parameter is encrypted, packed shellcode, or benign text, evaluate Shannon entropy through `call_mcp`. + +Depending on whether you are assessing an encoded representation directly or require true 8-bit raw-byte entropy, use one of the two workflows below: + +#### Workflow A: Direct Representation-Calibrated Entropy (`cyberchef_entropy`) +Pass the encoded string (Hex or Base64) directly to `cyberchef_entropy` without prior decoding: ```json { "tool": "call_mcp", @@ -88,6 +93,7 @@ When evaluating whether a payload or parameter is encrypted, packed shellcode, o } } ``` +`cyberchef_entropy` automatically detects the representation alphabet and returns `shannonEntropy`, `bitsPerChar`, `maxForAlphabet`, and `normalizedRatio` (saturation). > [!IMPORTANT] > **Calibrate entropy thresholds by input encoding representation:** @@ -99,11 +105,51 @@ When evaluating whether a payload or parameter is encrypted, packed shellcode, o > - **Base64 Strings (64 characters, max 6.0 bits/char)**: > - *Plain text Base64*: ~3.8 – 4.5 > - *High-entropy ciphertext / packed data*: **5.7 – 6.0** (Cannot exceed 6.0!) -> - **Raw Binary / Decoded Byte Streams (256 values, max 8.0 bits/byte)**: -> - *Plain text / uncompressed source code*: < 4.5 -> - *Compressed archives / packed code / encrypted shellcode*: > 7.2 -> -> **Best Practice**: Decode encoded representations (Hex, Base64) to raw bytes via `cyberchef_from_hex` or `cyberchef_from_base64` before evaluating raw Shannon entropy. +> - **Normalized Saturation Rule**: If `normalizedRatio >= 0.85` (or `verdict == "encrypted_or_compressed"`), the payload is near-maximal entropy for its alphabet, indicating encryption, CSPRNG keys, or compressed data. + +#### Workflow B: Atomic Raw-Byte Entropy via `cyberchef_bake` (Recommended for Raw Binary Streams) +To evaluate true 8-bit Shannon entropy (max 8.0 bits/byte) on an encoded payload (Base64 or Hex), execute the decode operation and entropy analysis **atomically** in a single `cyberchef_bake` recipe: +```json +{ + "tool": "call_mcp", + "arguments": { + "connection": "cyberchef", + "tool": "cyberchef_bake", + "arguments": { + "input": "rLYFVVXj/6ydut5XjZodQFTcIX3qdGy5lS4CBmdY...", + "recipe": [ + { "op": "From Base64" }, + { "op": "Entropy" } + ] + } + } +} +``` +For Hex-encoded payloads: +```json +{ + "tool": "call_mcp", + "arguments": { + "connection": "cyberchef", + "tool": "cyberchef_bake", + "arguments": { + "input": "4a8f1b9c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b...", + "recipe": [ + { "op": "From Hex", "args": ["None"] }, + { "op": "Entropy" } + ] + } + } +} +``` +This in-engine pipeline keeps raw decoded byte buffers in memory without serializing non-UTF-8 bytes across the JSON-RPC boundary. The returned entropy report uses the 8-bit raw alphabet (`maxForAlphabet: 8`): +- **Raw Binary / Decoded Byte Streams (256 values, max 8.0 bits/byte)**: + - *Plain text / uncompressed source code*: < 4.5 bits/byte + - *Compressed archives / packed code / encrypted shellcode*: > 7.2 bits/byte + +> [!CAUTION] +> **Do NOT attempt multi-turn raw byte passing across `call_mcp`:** +> `call_mcp` transports inputs and outputs over JSON-RPC strings. Arbitrary 8-bit binary bytes (such as non-printable ciphertext or compressed streams) cannot be safely represented or transported across JSON-RPC without corruption (mojibake, Unicode replacement characters `\uFFFD`, or truncation). Never call `cyberchef_from_base64` or `cyberchef_from_hex` and then attempt to pass the resulting string to `cyberchef_entropy` in a second `call_mcp` call. Always use `cyberchef_bake` to chain decoding and entropy atomically, or evaluate representation-calibrated entropy directly on the encoded string via `cyberchef_entropy`. ## Common Security Analysis Patterns @@ -125,9 +171,15 @@ When inspecting hardcoded binary strings, PowerShell scripts, or obfuscated malw 1. Identify probable key length or common plaintext prefix (e.g., `MZ`, `http`, `function`). 2. Run `call_mcp(connection="cyberchef", tool="cyberchef_xor", arguments={"input": data, "key": candidate_key})` iterating candidate keys to extract underlying C2 endpoints or script payloads. +### Pattern 4: Encrypted / Compressed Payload & Entropy Classification +When verifying whether an unknown string parameter is ciphertext, packed shellcode, or a high-entropy secret token: +1. **Calibrated check**: Call `call_mcp(connection="cyberchef", tool="cyberchef_entropy", arguments={"input": candidate})`. Inspect `normalizedRatio` and `verdict`. If `normalizedRatio >= 0.85`, it is probable ciphertext or compressed data. +2. **Raw-byte verification**: If strict 8-bit thresholds (> 7.2 bits/byte) are required, run `call_mcp(connection="cyberchef", tool="cyberchef_bake", arguments={"input": candidate, "recipe": [{"op": "From Base64"}, {"op": "Entropy"}]})` (or `From Hex`). + ## Critical Correctness Rules - **Use `call_mcp` Dispatch**: Never attempt to call CyberChef tools directly as top-level agent tools. Always dispatch through `call_mcp(connection="cyberchef", tool="...", arguments={...})`. +- **Atomic Raw-Byte Entropy Execution**: Never attempt to pass decoded raw binary bytes between separate `call_mcp` calls. JSON-RPC cannot transport arbitrary non-printable bytes without corruption. When evaluating raw byte entropy for Base64 or Hex payloads, always chain `From Base64`/`From Hex` and `Entropy` atomically in a single `cyberchef_bake` recipe. - **Do Not Guess Encodings**: If a string contains `=, %, 0x` or unexpected symbols, run `cyberchef_magic` first rather than blindly applying base64 or URL decoding. - **Preserve Raw Inputs**: Keep the original obfuscated string in agent memory/notes alongside the decoded output for accurate proof-of-concept (PoC) reporting. - **Fail-Safe Fallback**: If an operation fails during `cyberchef_bake`, isolate the failing recipe step and execute individual tools (`cyberchef_from_base64`, `cyberchef_url_decode`) sequentially via `call_mcp`.