Iom

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.

Quick Start

Starting the Client

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

Client startup parameters:

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.

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:

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

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:

Reference Documents