🔌 Developer API

Free, no-signup, curl-able JSON endpoints for the everyday pure-logic transforms — so you can wire CyberRamen into playbooks, Slack bots, SOAR actions and CI pipelines without opening a browser. This page is the complete guide: how to call it, what comes back, and a live example for every endpoint.

1. Quick start

Three calls from any terminal. Nothing to install beyond curl; jq is optional but handy.

# Defang a URL before pasting it into a ticket curl 'https://cyberramen.com/api/tools/defang?input=http://evil.example.com/login' # → {"mode":"defang","input":"http://evil.example.com/login","result":"hxxp[://]evil[.]example[.]com/login"} # Score a CVSS vector curl 'https://cyberramen.com/api/tools/cvss?vector=CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H' | jq .base_score # → 9.8 # Extract every IOC from a report (POST: no URL-encoding worries) curl -X POST 'https://cyberramen.com/api/tools/ioc-extract' -H 'Content-Type: application/json' \ -d "$(jq -Rs '{input: .}' < incident-report.txt)" | jq .iocs

Machine-readable: discovery of every endpoint at GET https://cyberramen.com/api/tools/, and an OpenAPI 3.0 document at https://cyberramen.com/api/tools/openapi.json for client generators, Postman/Insomnia imports and API monitors. Both carry an ETag and answer 304 to If-None-Match.

2. Making requests

3. Responses & errors

Always JSON (application/json; charset=utf-8), always a body. Success is 200 with the endpoint’s object. Anything else is an object with a single human-readable error string — test for the status code, then show .error.

Status	Meaning	Example
200	OK	the documented object
400	Your input could not be processed: missing parameter, bad CIDR, malformed token, unknown algo, invalid UTF-8…	{"error":"Prefix must be 0–32."}
404	Unknown endpoint path	{"error":"Unknown endpoint. See …/ for the endpoint list."}
405	Method other than GET / POST / HEAD / OPTIONS	{"error":"method_not_allowed"}
429	Rate limit hit — back off for the number of seconds in the Retry-After header	{"error":"Rate limit exceeded. …"}
500	Our fault. Please tell us.	{"error":"…"}

Determinism. The same input always produces the same output, except for fields that are explicitly about the current time: checked_at, certificate and JWT status/days_remaining, and STIX created/modified/valid_from. Responses carry Cache-Control: public, max-age=600; cache them freely.

Heuristics are labelled. Where an answer is a guess (hash-id candidates, ioc-extract, url-parse flags) the response says so in a note. Treat those as leads, not verdicts.

4. Endpoint reference

Each card shows the parameters, a ready-to-run curl line and the actual response — generated live by the same code that serves the API (clock pinned to 2027-01-15 for the time-dependent fields), so what you see is what you get. Long responses scroll inside their box; click the pill to collapse one.

5. Code examples

The same call — extract IOCs from a text blob via POST — in four environments. No SDK, no dependencies beyond the standard library.

bash + curl + jq

extract_iocs() { curl -sS -X POST 'https://cyberramen.com/api/tools/ioc-extract' \ -H 'Content-Type: application/json' \ -d "$(jq -Rn --arg t "$1" '{input: $t}')" } extract_iocs "$(cat report.txt)" | jq -r '.iocs.domains[], .iocs.ipv4[]'

Python 3 (standard library only)

import json, urllib.request def cyberramen(endpoint, **params): req = urllib.request.Request( f"https://cyberramen.com/api/tools/{endpoint}", data=json.dumps(params).encode("utf-8"), headers={"Content-Type": "application/json", "Accept": "application/json"}, method="POST", ) try: with urllib.request.urlopen(req, timeout=15) as r: return json.load(r) except urllib.error.HTTPError as e: # 4xx/5xx still carry a JSON body raise RuntimeError(json.load(e).get("error", str(e))) from None iocs = cyberramen("ioc-extract", input=open("report.txt", encoding="utf-8").read()) print(iocs["counts"]) bundle = cyberramen("stix", input="\n".join(iocs["iocs"]["domains"]), tlp="amber") open("indicators.stix.json", "w").write(json.dumps(bundle["bundle"], indent=2))

JavaScript (browser or Node 18+)

async function cyberramen(endpoint, params) { const r = await fetch(`https://cyberramen.com/api/tools/${endpoint}`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(params) }); const data = await r.json(); // errors are JSON too if (!r.ok) throw new Error(data.error); return data; } const { result } = await cyberramen('defang', { input: 'http://evil.example.com/x' }); const cvss = await cyberramen('cvss', { vector: 'CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H' }); console.log(result, cvss.base_score, cvss.severity);

PowerShell 7

$body = @{ input = (Get-Content .\report.txt -Raw) } | ConvertTo-Json $r = Invoke-RestMethod -Method Post -Uri 'https://cyberramen.com/api/tools/ioc-extract' ` -ContentType 'application/json' -Body $body $r.iocs.urls # GET works the same way for short inputs: (Invoke-RestMethod 'https://cyberramen.com/api/tools/hash-id?input=5d41402abc4b2a76b9719d911017c592').candidates

6. SOC recipes

Triage pipeline: report → IOCs → STIX bundle for your TIP

1. POST the raw report to /ioc-extract.
2. Join .iocs.urls, .iocs.domains, .iocs.ipv4, .iocs.sha256 with newlines.
3. POST that list to /stix with tlp, labels, valid_days and your producer name.
4. Import .bundle into MISP / OpenCTI / your TAXII server. Because indicator ids are stable, re-running the pipeline updates rather than duplicates.

curl -sS -X POST https://cyberramen.com/api/tools/ioc-extract -H 'Content-Type: application/json' \ -d "$(jq -Rs '{input: .}' < report.txt)" \ | jq -r '[.iocs.urls[], .iocs.domains[], .iocs.ipv4[], .iocs.sha256[]] | join("\n")' \ | jq -Rs '{input: ., tlp: "amber", labels: "malicious-activity", valid_days: 30, producer: "Blue Team"}' \ | curl -sS -X POST https://cyberramen.com/api/tools/stix -H 'Content-Type: application/json' -d @- \ | jq .bundle > indicators.stix.json

Safe-to-share ticket text

Before pasting an analyst note into Slack, Jira or an email, defang it wholesale so nobody clicks a live link by accident:

pbpaste | jq -Rs '{input: .}' | curl -sS -X POST https://cyberramen.com/api/tools/defang \ -H 'Content-Type: application/json' -d @- | jq -r .result | pbcopy # macOS; use xclip / Get-Clipboard elsewhere

Certificate expiry gate in CI

Fail a pipeline when a certificate your service ships has fewer than 30 days left:

days=$(curl -sS -X POST https://cyberramen.com/api/tools/cert-decode -H 'Content-Type: application/json' \ -d "$(jq -Rs '{input: .}' < deploy/tls/server.pem)" | jq .days_remaining) [ "$days" -ge 30 ] || { echo "certificate expires in $days days"; exit 1; }

Batch CVSS scoring from a CSV

# findings.csv: id,vector tail -n +2 findings.csv | while IFS=, read -r id vector; do printf '%s,%s\n' "$id" "$(curl -sS "https://cyberramen.com/api/tools/cvss?vector=$vector" | jq -r '"\(.base_score),\(.severity)"')" sleep 0.5 # stay well under 120 req/min done

Slack / Teams slash command

A /defang or /cvss command is a one-line proxy: forward the command text as input (or vector), return .result or .base_score. No key to store, no vendor account, and the endpoint never sees who asked.

7. Limits & fair use

8. Privacy & terms

Pure logic, no memory. Every endpoint is a deterministic function of its input: no external call is made on your behalf, nothing is stored, forwarded or logged beyond a short-lived, salted hash of the client address used for the rate limit. There are no accounts and no API keys, so there is nothing to leak. Still, the honest advice: do not send secrets, passwords or private keys to any remote API — the equivalent browser tools run entirely on your machine.

Same logic as the tools. Each endpoint mirrors a browser tool (IOC Defanger, CVSS Calculator, CIDR Calculator, JWT Decoder, Certificate Decoder, STIX Formatter…). Both implementations are checked against one shared set of test vectors, so a result you get here matches what the tool shows.

Licence. Provided as-is under CC BY 4.0 — attribution “CyberRamen.com”. No warranty; heuristic outputs should be verified before action. Questions, a bug, or a need for a higher limit? hello@cyberramen.com. Changes are announced in the changelog and its feed.

GRC datasets API — /api/v1/

Separate from the Tools API: read-only access to the governance/risk datasets (frameworks, control crosswalk, regulatory calendar, evidence lists). See /api/v1/ for its discovery document.