Kali Nmap Recon

Overview

Container-backed network discovery. The framework runs nmap inside a Kali Linux container per call, parses the output into typed findings, and hands them back to the agent as structured text — no nmap installation required on the host.

How it works

Built from KaliToolbox.nmap(): a single shared Kali Dockerfile (~2 GB, cached by SHA1 content hash) is built once and reused across all 18 Kali tools. Per-tool entrypoint override means each capability runs with its own command, env-var mapping, network mode, and timeout. Output goes through NmapOutputParser to produce typed Findings with normalised service names (ssl/http→https, microsoft-ds→smb).

Example

When a user asks:

Audit the network 192.168.1.0/24 — discover live hosts and inventory their services.

the agent calls the tool:

kali_nmap(target="192.168.1.0/24")

and gets back: kali_nmap: 4 finding(s) — 192.168.1.1:80 http (lighttpd 1.4.71), 192.168.1.1:443 https, 192.168.1.5:22 ssh (OpenSSH 9.2p1), 192.168.1.10:445 smb

Configuration

Set these before calling the tool. Values marked required must be present or the tool call will fail.

swarmai.skill.container.runtime required

Auto-configured ContainerSkillRuntime singleton. Requires a working Docker daemon on the host.

swarmai.skill.container.policy.allowed-base-images optional

Allowlist for FROM images. Defaults to alpine, kalilinux/kali-rolling, python:* — extend per deployment.

swarmai.skill.container.approval-gate optional

Pluggable image-approval gate (Auto/Console/Remembering/Callback). Defaults to AutoApprovalGate.

Use it in a workflow

Wire this tool into a SwarmAI crew. Use the YAML DSL for declarative workflows, or the Java builder API when you want full programmatic control.

YAML DSL

# kali-audit.yaml
name: kali-audit-crew
process: SEQUENTIAL
agents:
  - id: auditor
    role: Senior network security analyst
    goal: Audit a network range, then write a Markdown report
    tools:
      - kali_nmap
      - kali_whatweb
      - kali_smbmap
      - kali_ssh_audit
tasks:
  - id: audit-task
    agent: auditor
    description: Audit 192.168.1.0/24, follow up on each interesting service, produce a findings report.

Java

import ai.intelliswarm.swarmai.agent.Agent;
import ai.intelliswarm.swarmai.skill.runtime.ContainerSkillRuntime;
import ai.intelliswarm.swarmai.skill.runtime.KaliToolbox;
import ai.intelliswarm.swarmai.task.Task;
import ai.intelliswarm.swarmai.tool.base.BaseTool;
import java.util.List;

ContainerSkillRuntime runtime = new ContainerSkillRuntime();
KaliToolbox toolbox = new KaliToolbox(runtime);
List<BaseTool> tools = toolbox.all();   // 18 callable tools

Agent auditor = Agent.builder()
    .role("Senior network security analyst")
    .goal("Audit the target network and produce a findings report")
    .chatClient(chatClient)
    .tools(tools)
    .build();

Task audit = Task.builder()
    .description("Audit 192.168.1.0/24 — start with kali_nmap, follow up on each open service.")
    .agent(auditor)
    .build();

What it's good for

Real scenarios where agents put this tool to work.

Network discovery + service-version inventory across a CIDR

First-step reconnaissance in a multi-tool reactive audit

Pre-deployment scan of a target environment from a build agent

Compose with kali_whatweb / kali_smbmap / kali_ssh_audit for end-to-end posture review

Source

Implementation lives at swarmai-core/src/main/java/ai/intelliswarm/swarmai/skill/runtime/KaliToolbox.java in the swarm-ai repository.

Open kali_nmap on GitHub →