IoM User Guide

IoM (Implant-over-Middleware) is a modular C2 framework built on a three-layer architecture.

Architecture Overview

┌──────────────────────────────┐
│     Client (CLI/TUI)         │  User interaction layer
│  Cobra commands + Bubble Tea │
└──────────────┬───────────────┘
               │ gRPC + mTLS
               ▼
┌──────────────────────────────┐
│     Server                   │  Control hub
│  Session/Task/Event mgmt     │
│  Listener/Pipeline dispatch  │
└──────────────┬───────────────┘
               │ ListenerRPC
               ▼
┌──────────────────────────────┐
│  Listener → Pipeline         │  Communication middleware
│  TCP / HTTP / Bind / Custom  │
└──────────────┬───────────────┘
               │ Network
               ▼
┌──────────────────────────────┐
│     Implant (malefic)        │  Target-side agent
│  Modular capability manifest │
└──────────────────────────────┘

Core Concepts

See reference/concepts.md for detailed explanations.

Concept	Summary
Session	An active implant connection containing target system info, a task queue, and module capabilities
Listener	A network service that accepts implant connections and manages multiple pipelines
Pipeline	A transport channel under a listener, responsible for encryption, protocol parsing, and frame handling
Task	An execution unit sent to the implant, with status tracking and timeout control
Module	A capability category declared by the implant, determining which commands are available
Event	A real-time notification (new session, task completion, session offline, etc.)

Quick Start

Starting the Client

iom login server.auth            # Log in using a .auth file

Client startup parameters:

Parameter	Description
--mcp <addr>	Enable MCP server (e.g., 127.0.0.1:5005)
--rpc <addr>	Enable LocalRPC gRPC server
--daemon	Daemon mode — run in background without interactive terminal
--tui	TUI multiplexing mode (split-pane terminal)
--quiet	Quiet mode — suppress startup event output

Authentication and Configuration

The .auth file contains mTLS certificates and the server address. It serves as the credential for connecting to the server.

Configuration directory structure (see reference/config.md for details):

~/.config/malice/
├── malice.yaml          # Client configuration (MCP, RPC, logging, etc.)
├── configs/             # .auth file storage (auto-migrated after login)
├── log/                 # Log files
├── resources/           # Resource files
└── temp/                # Temporary files

Basic Operations

Session Management

session                          # List active sessions
session --all                    # List all sessions (including offline)
use <session_id>                 # Enter a session context (supports ID prefix matching)
background                       # Exit the current session and return to the main menu

Common Commands Within a Session

sysinfo                          # System information
whoami                           # Current user
privs                            # Current privileges
ps                               # Process list
ls / cd / pwd / cat              # File system operations
upload <local> <remote>          # Upload a file
download <remote>                # Download a file
shell <command>                  # Execute a shell command

Infrastructure Management

listener                         # List listeners
pipeline list                    # List pipelines
pipeline tcp --name <n> --host <h> --port <p>   # Create a TCP pipeline

Task Management

tasks                            # List tasks
tasks --task-id <id>             # View task details
tasks cancel --task-id <id>      # Cancel a task

Module Management

modules list                     # View available modules
modules refresh                  # Refresh modules from the implant
modules load <addon>             # Load an extension module

Command Categories

IoM commands are organized by function. See reference/commands.md for the full reference.

Category	Description	Examples
Basic	Info, heartbeat, binding	sysinfo, sleep, suicide
Execution	Run programs and code	shell, execute_exe, execute_assembly, bof
File System	Browse and manipulate files	ls, cd, cat, rm, mkdir, cp, mv
File Transfer	Upload and download	upload, download
System	System operations	ps, kill, env, netstat, whoami
Privileges	Privilege management	privs, getsystem, runas, rev2self
Network	Proxying and forwarding	proxy, forward, reverse
Enumeration	Environment discovery	enum av, enum software, enum dc

MAL Plugins

IoM extends its command capabilities through MAL (a Lua plugin system). The built-in community plugin package provides 90+ commands covering enumeration, privilege escalation, credential harvesting, lateral movement, persistence, and more.

mal list                             # List installed plugins
mal install <name>                   # Install from the community repository
mal remove <name>                    # Uninstall
search_commands("keyword")           # Search for plugin-provided commands

See reference/mal-usage.md for MAL usage details. See reference/builtin-plugins.md for the full built-in command list.

MCP Tool Interface

The IoM client provides an MCP server that exposes the following tools:

Tool	Purpose
search_commands	Fuzzy-search commands by name/description, returns lightweight summaries
execute_command	Execute any client command, automatically waits for the task result
execute_lua	Execute a Lua script (with access to all IoM internal APIs)
get_history	Retrieve output from historical tasks

Recommended workflow (progressive discovery):

1. search_commands("keyword") — search for related commands
2. execute_command("<cmd> --help") — view specific usage
3. execute_command("<cmd> <args>") — execute the command

Lua Script Execution

Use execute_lua to run Lua scripts directly for automation and batch operations:

-- Simple example
execute_lua('return string.format("2+2=%d", 2+2)')

-- Use IoM APIs within a session context
execute_lua('local s = active(); return s.Os.Hostname', session_id="abc123")

See reference/lua-scripting.md for details.

Troubleshooting

See reference/troubleshooting.md for common issues, covering:

• Connection failures (auth files, certificates, network)
• Session anomalies (offline, heartbeat timeout, unavailable modules)
• Task issues (stuck, timed out, no output)
• Debugging methods (log directory, audit log level)

Documentation and Community

Resource	Link
Official Wiki	https://chainreactors.github.io/wiki/IoM/
Quick Start	https://chainreactors.github.io/wiki/IoM/quickstart/
Implant Manual	https://chainreactors.github.io/wiki/IoM/manual/implant/
MAL Scripting	https://chainreactors.github.io/wiki/IoM/manual/mal/quickstart/
Roadmap	https://chainreactors.github.io/wiki/IoM/roadmap/
GitHub (Server)	https://github.com/chainreactors/malice-network
GitHub (Implant)	https://github.com/chainreactors/malefic

Reporting Issues

Submit feedback via GitHub Issues:

# Create an issue using gh cli
gh issue create --repo chainreactors/malice-network \
  --title "Brief description of the issue" \
  --body "## Environment
OS:
IoM version:
## Steps to Reproduce
1.
2.
## Expected Behavior

## Actual Behavior

## Logs
(Paste relevant logs from ~/.config/malice/log/)"

When filing an issue, include: OS, IoM version, reproduction steps, expected vs. actual behavior, and relevant logs.

Related Skills

IoM capabilities are split across multiple skills by responsibility. Consult the appropriate skill for your scenario:

Skill	Responsibility	Use When
iom (this skill)	Core concepts, usage guide, configuration, troubleshooting	"How do I connect", "How to use commands", "I got an error"
iom-pentest	Penetration testing execution	"Privilege escalation", "Lateral movement", "Credentials", "Persistence"
iom-opsec	Operational security methodology and case studies	"Is this safe", "Will it be detected", "Risk assessment"
mal-develop	MAL plugin development	"Write a plugin", "Extend commands", "Lua API"

Reference Documents

Topic	Reference File
Core concept details	reference/concepts.md
Command quick reference	reference/commands.md
MAL plugin usage	reference/mal-usage.md
Built-in plugin command list	reference/builtin-plugins.md
Lua script execution	reference/lua-scripting.md
Troubleshooting	reference/troubleshooting.md
Configuration details	reference/config.md