Skip to content

API.md

Latest commit

 

History

History
411 lines (313 loc) · 8.43 KB

API.md

File metadata and controls

411 lines (313 loc) · 8.43 KB
Raw

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.