JSON Contracts, KittyForge, and Interoperability

A good interactive tool impresses during the demo. A good professional tool remains usable after the demo. That is exactly the role of JSON contracts: they let the console, API, MCP server, portal, reports, plugins, and tests speak the same language.

In KittySploit, schemas live in core/schemas/json/v1/. The current instance contract uses schema_version: "1.0". The Python helper core.schemas exposes list_schemas(), schema_path(), and load_schema().

Contract Families

`evidence`	Structured proof: HTTP, command output, capture, log, manual note.
`finding`	Exploitable vulnerability or observation: severity, evidence, status, retest.
`job`	Asynchronous execution of a module or workflow.
`session`	Interactive or persistent channel: shell, browser, meterpreter-like, etc.
`report`	Final bundle: targets, findings, evidence, jobs, sessions, summary.
`agent_*`	Agent action, observation, decision, state, and complete run.
`generated_artifact`	Output produced by a KittyForge or API generator.
`kittyforge_graph`	Operational graph: nodes, relations, summary.
`kittyforge_error`	Normalized API error with code, message, field, module, and `request_id`.
`signed_package`	Signed package manifest: checksums, signature, algorithm, files.

The Agent as Observable Story

Agent schemas tell an autonomous campaign in a readable form:

agent_action: what is proposed or executed, with risk and approval.
agent_observation: what was collected, in which phase, with what evidence.
agent_decision: why the agent continues, changes documentation, or stops.
agent_state: current run state.
agent_run: complete container: target, actions, observations, decisions.

KittyForge: Generation, Graphs, and Packages

In this documentation, KittyForge can be read as the layer that transforms framework outputs into shareable objects: generated artifacts, operational graphs, standardized API errors, and signed packages.

Generated Artifacts

generated_artifact describes output produced by a generator: content type, size, artifacts, metadata, warnings, and logs. Useful for api_import, module generators, packs, or any feature that does not settle for displaying text.

Operational Graph

kittyforge_graph structures relationships:

{
  "schema_version": "1.0",
  "nodes": [
    {"id": "target:dvwa", "kind": "target", "label": "DVWA local"},
    {"id": "finding:headers", "kind": "finding", "label": "Headers manquants"}
  ],
  "edges": [
    {"from": "finding:headers", "to": "target:dvwa", "relation": "observed_on"}
  ],
  "summary": {
    "scope": "isolated test environment",
    "confidence": "usage"
  }
}

This graph does not replace the report. It helps reread relationships: which evidence supports which finding, which module observed which target, which decision followed which observation.

API Errors

kittyforge_error imposes a minimum of clarity: code, message, request_id, and optionally field, module, details. For an external interface, this is crucial: an error must help fix the problem, not just say ``it doesn't work''.

Signed Packages

signed_package describes a KittyForge package with checksums and

Recommended Quality Cycle

When you add a feature that produces data, use this cycle:

Identify the produced object: target, evidence, finding, job, agent observation, artifact.
Check if a schema already exists.
Produce a minimal valid example.
Add or adapt a test in tests/test_json_schemas.py.
Link the object to a consumer: report, API, MCP, marketplace, or detection pack.

pytest tests/test_json_schemas.py

Workshop: Transform Raw Output into Evidence

Take a simple isolated test environment observation: a missing header, a discovered endpoint, a server banner, a completed job. Your goal is not to dramatize it, but to structure it.