Air

You can interact with Binalyze AIR through a dedicated MCP server that translates natural language questions into actionable forensic, incident response, and asset management tasks. This bridge lets you retrieve data, manage cases, run acquisitions, and configure policies without writing code.

How to use

You connect an MCP client to the air_mcp server and start asking for information or actions in plain language. The server exposes capabilities across assets, acquisitions, cases, policies, users, audit logs, and organization management, so you can list items, view details, assign tasks, run acquisitions, export data, and more. Begin with high-level requests like listing assets or cases, then drill into specifics such as an asset by ID, a case's tasks, or a particular acquisition profile. You can also initiate operational tasks such as rebooting endpoints, isolating machines, or retrieving logs, all through natural language prompts.

Practical usage patterns include: - List assets to inventory your environment. - Get asset details by ID to review hardware, OS, and status. - List and manage acquisition profiles to tailor evidence collection. - Assign acquisition tasks to endpoints using a chosen profile. - Create and manage cases, policies, and organizations. - Retrieve audit logs or export case data for reporting. - Tag assets automatically based on rules and check policy matches against assets.

How to install

# Prerequisites: ensure Node.js and npm are available on your system
node -v
npm -v

# Local development setup
# Clone the MCP server
git clone https://github.com/binalyze/air-mcp

# Change directory
cd air-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Start the server (if a start script is provided in your setup)
# npm run start

Additional sections

Configuration and runtime details are focused on how you connect clients to the MCP server and what environment variables you must provide. An API token is required for authentication and should be supplied via the AIR_API_TOKEN environment variable. The server can be configured to listen to a remote endpoint or run locally via a command that invokes the MCP package through your MCP client.

Security note: keep your API token secret and rotate credentials regularly. Use network access controls to limit who can reach the MCP server, and enable auditing to track actions performed via the MCP interface.

MCP configuration and environment

The following client configuration demonstrates how to connect using a standard MCP client. It runs the MCP package via npx and passes through required environment variables for host and API authentication.

{
  "mcpServers": {
    "air-mcp": {
      "command": "npx",
      "args": ["-y", "@binalyze/air-mcp"],
      "env": {
        "AIR_HOST": "your-api-host.com",
        "AIR_API_TOKEN": "your-api-token"
      }
    }
  }
}

Tools and capabilities overview

This MCP server provides a broad set of capabilities that you can access with natural language prompts. Some of the major areas include asset management, acquisition orchestration, case and policy administration, triage rule handling, log retrieval, repository management, and organizational controls.

Troubleshooting and notes

If you cannot reach the MCP server, verify that AIR_HOST is reachable from your MCP client network and that AIR_API_TOKEN is valid. Check that the client configuration uses the exact server name recognized by your MCP client, and ensure the environment variables are correctly passed to the process. If a task fails, inspect the audit logs and case activity exports to determine where the failure occurred.

Available tools

List assets

Return a list of assets in your organization, including OS and platform details.

Asset details

Fetch detailed information for a specific asset by its ID.

Asset tasks

Retrieve all tasks associated with a specific asset by its ID.

Acquisition profiles

List available acquisition profiles.

Acquisition tasks

Assign evidence acquisition tasks to endpoints using a chosen profile.

Image acquisition tasks

Assign disk image acquisition tasks to endpoints.

Baseline acquisition

Acquire baseline data from specific endpoints to establish a reference point.

Compare baseline

Compare multiple baseline acquisition tasks for a specific endpoint to identify changes.

Get comparison report

Retrieve a comparison report for a specific endpoint and task.

Create acquisition profile

Create new acquisition profiles with specified evidence/artifact/network settings.

Acquisition artifacts

List available artifacts for evidence collection.

Acquisition evidences

List available evidence items for forensic data collection.

Reboot tasks

Assign reboot tasks to specific endpoints.

Shutdown tasks

Assign shutdown tasks to specific endpoints.

Isolation tasks

Isolate or unisolate specific endpoints.

Log retrieval tasks

Retrieve logs from specific endpoints.

Version update tasks

Assign version update tasks to specific endpoints.

Organization management

List organizations.

Case management

List cases in your organization.

Policy management

See security policies across your organization.

Task management

Track forensic collection tasks and their statuses.

Triage rules

View YARA, Osquery and Sigma rules for threat detection.

User management

List users in your organization.

User details

Get detailed information about a specific user by their ID.

Drone analyzers

View available drone analyzers with supported operating systems.

Audit log export

Initiate an export of audit logs.

List audit logs

View audit logs from the system.