Docs / Getting started / Architecture Overview
GitHub

Getting started

Architecture Overview

This chapter is not an advanced development documentation. It is a map. Before entering long campaigns, it helps explain why KittySploit sometimes feels like a city: there are streets, buildings, public services, workshops, checkpoints, and archives.

The district map

interfaces/command_system/The control tower: parsing, completion, history, command registry.
interfaces/command_system/builtin/Operator stations: agent, scanner, isolated test environment, proxy, campaign, etc.
core/Shared services: framework, workspaces, sessions, Guardian, schemas, loading, validation.
modules/Technical workshops: scanners, exploits, payloads, isolated test environment post-exploitation, listeners, forensic.
lib/Reusable tools: HTTP clients, parsing, protocol helpers, detection.
kittyproxy/Web observation post: streams, replay, endpoints, API, GraphQL, context.
plugins/External connectors: Metasploit, ngrok, OSINT, routers, specialized scanners.
core/schemas/json/v1/Contracts: evidence, finding, job, session, agent, report, KittyForge.

A command's path

The typical flow looks like this:

Utilisateur -> console -> CommandRegistry -> BaseCommand.execute() -> services core -> module or workflow -> ModuleResult / job / session / finding -> workspace, rapport, agent, portal, detection pack

This diagram explains an essential point: a KittySploit command is almost never a simple print. It often modifies mission state. It can create a note, record a host, feed a campaign, open a job, produce evidence, or trigger a Guardian check.

When you learn a command, always ask: what state does it read, what state does it modify, and which other component can reuse its result?

Three guided tours

Tour 1: a web scan

scanner receives a URL and consults the scope. The engine selects compatible HTTP modules. Each module observes a signal: banner, header, endpoint, sensitive file. Results are deduplicable, transformable into hosts, vulns, or evidence. The final report does not include everything: it selects useful evidence.

Tour 2: an agent decision

agent reads target, workspace, policy, and budgets. The module catalog proposes possible actions. The security profile and Guardian limit the plan. An action becomes observation; observation becomes decision. agent_run, agent_observation, and agent_decision make it all readable.

Tour 3: a shared artifact

api_import or a generator produces modules or artifacts. Output schemas describe content, size, warnings, and metadata. A signed package can be verified before installation. The marketplace, API, or portal can consume the same object without guessing its format.

Trust architecture

In a security tool, architecture serves not only to go fast. It serves to avoid fuzzy actions.

Mechanism		Why it matters
workspaceSeparates missions and avoids mixing evidence.
historyMakes actions readable afterward.
GuardianAlerts on sensitive signals, forbidden hosts, honeytokens, or risky behavior.
ModuleResultNormalizes what a module claims to have produced.
JSON schemasStabilize objects shared between console, API, MCP, reports, and portal.
TestsPrevent a brilliant feature from becoming fragile at the next evolution.
New isolated test environment modulemodules/ + labs/ if scoring required
New console commandinterfaces/command_system/builtin/ + registry
New external integrationplugins/ or interfaces/ depending on exposure level
New evidence formatcore/schemas/json/v1/ + validation tests
New report or exportcore/, interfaces/api_server.py, campaign, or reporting module
New autonomous workflowinterfaces/command_system/builtin/agent/