API.md

Marble Framework REST API Documentation

Version: 2.0.0
Base URL: http://<host>:<port>/api/v1
Default port: 5000
Interactive docs: http://<host>:<port>/api/v1/docs
OpenAPI spec: http://<host>:<port>/api/v1/openapi.json

---

Starting the API Server

# Via the unified launcher
./marble api --port 5000

# Via Python directly
python3 ml/api.py --port 5000 --host 0.0.0.0

# With debug mode
python3 ml/api.py --port 5000 --debug

Requirements: pip install flask

---

Health & Info

GET /health

Health check endpoint.

Response:

{"status": "ok", "timestamp": 1719480000.0}

GET /version

Version and algorithm count.

Response:

{"version": "2.0.0", "name": "Marble Framework REST API", "algorithms": 126}

GET /status

Full pipeline status including build state, validation/detection results, RL training, and novel generation results.

Response:

{
  "version": "2.0.0",
  "algorithms_count": 126,
  "features_count": 106,
  "validation_passed": true,
  "detection_passed": true,
  "rl_best_reward": 3.5,
  "rl_episodes": 100,
  "novel_best": {"name": "MBL_GEN_0032", "score": 112.0, "family": "BUMP"},
  "mibster_built": true,
  "mender_built": true,
  "validator_built": true,
  "timestamp": 1719480000.0
}

---

Algorithm Catalog

GET /algorithms

List all registered algorithms.

Response:

[
  {"name": "MBL_FORLOOP_XOR1", "family": "XOR", "direction": "forward", "key_size": "1BYTE"},
  {"name": "MBL_CLASS_BUMP3", "family": "BUMP", "direction": "forward", "key_size": "8BYTE"},
  {"name": "MBL_GEN_0032", "family": "BUMP", "direction": "backward", "key_size": "8BYTE"}
]

GET /algorithms/{name}

Get details for a specific algorithm.

Parameters:

• name (path, required) — Algorithm name, e.g. MBL_FORLOOP_XOR1

Response: Algorithm object or 404 if not found.

GET /algorithms/search?q={query}

Search algorithms by keyword (matches name, family, direction, key_size).

Parameters:

• q (query, required) — Search query

Example:

curl "http://localhost:5000/api/v1/algorithms/search?q=XOR"

---

Obfuscation Tools

POST /obfuscate

Run the mibster obfuscator on a project directory.

Request body:

{
  "project_dir": "/path/to/project",
  "output_dir": "/path/to/output",
  "shared_dir": "/path/to/Shared",
  "dry_run": false
}

Field	Type	Required	Description
project_dir	string	yes	Path to project directory with source files
output_dir	string	yes	Output directory for MarbleReceipt.txt
shared_dir	string	no	Path to Shared/ directory (default: built-in)
dry_run	boolean	no	Preview without modifying files (default: false)

Example:

curl -X POST http://localhost:5000/api/v1/obfuscate \
  -H "Content-Type: application/json" \
  -d '{"project_dir":"/home/user/myproject","output_dir":"/tmp/output"}'

POST /mend

Run the mender to restore obfuscated source files.

Request body:

{"project_dir": "/path/to/project"}

POST /validate-binary

Run the validator to check a compiled binary for plaintext strings.

Request body:

{
  "receipt": "/path/to/MarbleReceipt.txt",
  "binary": "/path/to/compiled_binary"
}

---

ML Pipeline — Reports

GET /ml/features

Get extracted AST features from all algorithms (from extract_features.py).

GET /ml/validation-report

Get the Z3 symbolic validation report.

GET /ml/detection-report

Get the detection evasion (YARA) report.

GET /ml/training-results

Get RL training results and episode history.

GET /ml/novel-results

Get novel algorithm generation and evaluation results.

---

ML Pipeline — Actions

POST /ml/extract

Run AST feature extraction on all algorithms.

curl -X POST http://localhost:5000/api/v1/ml/extract

POST /ml/validate

Run the Z3 symbolic validation pipeline.

POST /ml/detect

Run detection evasion check (YARA rules).

POST /ml/generate

Generate new algorithms using template/LLM generation.

Request body (all optional):

{
  "family": "XOR",
  "count": 5,
  "direction": "forward",
  "key_size": "8BYTE"
}

Field	Type	Default	Options
family	string	"XOR"	XOR, BUMP, RBUMP, RXOR
count	integer	5	1–100
direction	string	—	forward, backward
key_size	string	—	1BYTE, 8BYTE, 16BYTE

POST /ml/novel-generate

Generate novel algorithms via LoRA-trained model.

Request body (all optional):

{
  "count": 10,
  "temperature": 0.9,
  "model_path": "models/rl_output"
}

POST /ml/rltrain

Run RL training loop.

Request body (all optional):

{
  "episodes": 10,
  "mode": "lightweight",
  "population": 5,
  "seed": 42
}

Field	Type	Default	Options
episodes	integer	10	1–1000
mode	string	"lightweight"	lightweight, full
population	integer	5	1–50
seed	integer	42	—

POST /ml/inject

Generate and inject an algorithm directly into the Marble framework source files.

Request body (all optional):

{
  "family": "BUMP",
  "direction": "backward",
  "key_size": "8BYTE"
}

POST /ml/dedup

Find and optionally remove structurally duplicate algorithms.

Request body (all optional):

{
  "threshold": 0.05,
  "remove": false
}

POST /ml/camouflage

Run entropy camouflage / build fingerprint randomization.

Request body:

{
  "subcmd": "fingerprint",
  "seed": 42,
  "input": "obfuscated.cpp",
  "output": "camouflaged.cpp"
}

Field	Type	Default	Options
subcmd	string	"fingerprint"	fingerprint, full
seed	integer	—	Random seed
input	string	—	Input source file (for full mode)
output	string	—	Output file (for full mode)

---

Novel Algorithms

GET /novel-algorithms

List all generated novel algorithms with validation scores.

Response:

[
  {
    "name": "MBL_GEN_0032",
    "family": "BUMP",
    "novel_mode": "position_dep",
    "direction": "backward",
    "score": 112.0,
    "overall_passed": true
  }
]

GET /novel-algorithms/{name}

Get full details of a novel algorithm including source code and validation report.

Parameters:

• name (path, required) — Algorithm name, e.g. MBL_GEN_0032

---

Receipts

GET /receipts

List all TTL receipts.

Response:

[
  {"name": "receipt_001.ttl", "size": 1024},
  {"name": "receipt_002.ttl", "size": 2048}
]

POST /receipts/cleanup

Remove expired receipts.

Response:

{"success": true, "message": "Cleaned up 3 expired receipts", "removed": 3}

---

Specification

GET /openapi.json

Returns the full OpenAPI 3.0 specification as JSON.

GET /docs

Returns an interactive HTML documentation page with all endpoints, parameters, and curl examples.

---

Error Handling

All errors return JSON with an error field:

{"error": "Algorithm 'MBL_FOO' not found"}

Status	Description
200	Success
400	Bad request (missing required parameters)
404	Resource not found
500	Internal server error

---

Python Client Example

import requests

BASE = "http://localhost:5000/api/v1"

# Get status
r = requests.get(f"{BASE}/status")
print(r.json())

# List algorithms
r = requests.get(f"{BASE}/algorithms")
for alg in r.json():
    print(alg["name"], alg["family"])

# Obfuscate a project
r = requests.post(f"{BASE}/obfuscate", json={
    "project_dir": "/home/user/myproject",
    "output_dir": "/tmp/output"
})
print(r.json())

# Generate novel algorithms
r = requests.post(f"{BASE}/ml/novel-generate", json={
    "count": 10,
    "temperature": 0.9
})
print(r.json())

# Run RL training
r = requests.post(f"{BASE}/ml/rltrain", json={
    "episodes": 50,
    "mode": "lightweight"
})
print(r.json())

---

Integration with Dashboard

The REST API (api.py) and the web dashboard (dashboard.py) are separate servers:

Server	Port	Purpose
api.py	5000	REST API for programmatic access
dashboard.py	8080	Web UI for visual monitoring

They can run simultaneously. The dashboard also has its own built-in API endpoints at /api/ for the UI buttons.