API teatmik

Nullist töötava integratsioonini 5 minutiga. Loo tasuta võti aadressil /signup — tasuta paketis 10 000 külastajakontrolli kuus, ilma kaardita.

// STEP 1 — HTML. Load the collector before your form handler.
<script defer src="https://maskbreak.com/assets/sentinel.js"></script>
<form class="monocle-enriched" id="login-form">
  <input type="email" name="email" required>
  <button type="submit">Continue</button>
</form>

// STEP 2 — Your frontend script, after the SDK loads.
document.getElementById('login-form').addEventListener('submit', async (event) => {
  event.preventDefault();
  const { token, fingerprintEventId, tz } = await window.Sentinel.collect();
  const response = await fetch('/your-login-endpoint', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      email: event.target.email.value, token, fingerprintEventId, tz
    })
  });
  // Handle response.status and the next step in your existing login UI.
});

// STEP 3 — Node 22 / Express backend.
// express, app and existingLoginHandler belong to your application.
// This check is NOT authentication and never creates a login session.
app.use(express.json({ limit: '16kb' }));
app.post('/your-login-endpoint', async (req, res, next) => {
  try {
    const { token, fingerprintEventId, tz, email } = req.body;
    const response = await fetch('https://maskbreak.com/v1/evaluate', {
      method: 'POST',
      signal: AbortSignal.timeout(2000), // example budget; measure your own
      headers: {
        'Authorization': 'Bearer ' + process.env.MASKBREAK_API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ token, fingerprintEventId, tz, email })
    });
    if (!response.ok) throw new Error('Visitor check unavailable');
    const result = await response.json();
    // Production gate: never authorize from a fixture or personal test key.
    // Use a live key in MASKBREAK_API_KEY; test the integration separately.
    if (result.test || result.sandbox || result.sample) {
      throw new Error('Synthetic visitor check');
    }
    if (!['allow', 'review', 'block'].includes(result.decision)) {
      throw new Error('Unexpected verdict');
    }
    if (result.decision === 'block') {
      return res.status(403).json({ error: 'Action refused by policy' });
    }
    if (result.decision === 'review' || result.degraded) {
      // Implement an actual step-up flow; never mint a session here.
      return res.status(409).json({ next: 'step_up' });
    }
    req.fraudCheck = result;
    return next(); // normal credential + authorization checks still run
  } catch {
    // Example temporary hold. Choose a fallback for each business action.
    return res.status(503).json({ error: 'Check unavailable; try again shortly' });
  }
}, existingLoginHandler);

Enne otsuse jõustamist

Testi eraldi tavapäraseid otsuseid, puuduvat teavet ja kliendi võimalusi pärast takistust jätkata. Need juhendid käsitlevad rakendusepoolseid valikuid, mida API vastus sinu eest teha ei saa.

• Kavanda ajalõpu korral kasutatav varulahendus
• Plaani turvaline kasutuselevõtt

Kutsu liivakasti otspunkti ühe klõpsuga. Ilma registreerumiseta, ilma API-võtmeta — ainult päris /v1/evaluate vastuse kujud, mida saad oma koodi kopeerida.

GET https://maskbreak.com/v1/evaluate/sample
   ?scenario=clean

{
  "click ▶ Run Request": "to see live JSON"
}

Tootmispäringud kasutavad POST /v1/evaluate koos SDK-lt saadud token-iga ja päisega Authorization: Bearer sk_live_.... Näidisotspunkt tagastab sama vastuse kuju, nii et saad oma parsimisloogika enne registreerumist valmis ehitada.

POST https://maskbreak.com/api/lookup
{ "ip": "185.220.101.34" }

{
  "click ▶ Run Lookup": "for a live verdict on this IP"
}

Kuidas see töötab

Maskbreak kasutab kolmeastmelist voogu klient → sinu taustsüsteem → Maskbreaki API, et su salajane võti ei jõuaks kunagi brauserisse.

Autentimine

Kõik päringud otspunktile /v1/evaluate peavad sisaldama sinu salajast API-võtit Bearer-tokenina. Oma võtme leiad töölaualt.

Võtme vahetamine

Vaheta võtit konsoolist (Integratsioon → Vaheta või Seaded → API võtmed; parooli küsitakse uuesti). Uus võti töötab kohe ja eelmine võti töötab veel 24 tundi, nii et juurutus saab üle minna ilma pausita. Kui võti on lekkinud, lõpetab Seadetes Tühista vana võti kohe selle armuaja otsekohe. Armuaja jooksul arvestatakse mõlema võtme päringud samast tunnilimiidist ja /v1/usage näitab mõlemale samu numbreid.

Igal kontol on isiklik sk_test_… võti. See käivitab reaalajas kontrolliahela ja salvestab testsündmused, kuid ei saada pärisliikluse veebihaagi teavitusi; selle kontrollid lähevad sinu kuulimiidi sisse, sellel on oma tunnilimiit ning sellele ei rakendata IP-lubamisnimekirja. Avalik sk_test_sandbox võti vastab ainult deterministlikele testtokenitele, ilma kontota ja sündmusi salvestamata. Tootmisvõtme IP-lubamisnimekiri piirab /v1/evaluate ja /v1/lookup kasutamist ning tokeni väljastamist otspunktilt /oauth/token (muult aadressilt 400 unauthorized_client), kuid mitte /v1/usage kasutamist.

OAuth 2.0 Client Credentials Uus

Vaheta oma konto e-post ja API-võti lühiajalise bearer-tokeni vastu standardse client_credentials grandiga. Token kannab sinu konto ID-d, mitte kunagi võtit ennast. See kehtib 60 minutit, autendib sinu parasjagu kehtiva sama tüüpi võtmena ning on seotud võtmega, millega see vermiti: pärast vahetamist töötab see edasi seni, kuni see võti kehtib (eelmise võtme 24-tunnine armuaeg); eelmise võtme tühistamine, teine vahetus või testvõtme vahetamine lõpetab selle kohe vastusega 401 — siis vermi uus. Sinu sk_test_ võtmega vermitud token jääb testtunnuseks. API-võtmed töötavad täpselt nagu varem; see on lisandus.

curl -X POST https://maskbreak.com/oauth/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type":"client_credentials","client_id":"your@email.com","client_secret":"sk_live_..."}'

Kasuta tagastatud access_token-i Authorization: Bearer päises kõikjal, kus API-võtit aktsepteeritakse. Tokenid aeguvad; uuenda vahetust korrates. Võti ise ei lahku kunagi sinu serverist.

Lisa Maskbreaki SDK igale lehele, kus tahad kasutajaid hinnata. Üks skript laadib mõlemad tuvastuskihid — võrguanalüüs (VPN, proksi, andmekeskus) ja seadmeanalüüs (antidetect-brauserid, botid, võltsimine) — ning lisab mõlemad tokenid sinu vormidesse.

<!-- Maskbreak SDK — network + device, paste inside <head> -->
<script async src="loading..."></script>

<!-- Add class="monocle-enriched" to any form you want evaluated -->
<form class="monocle-enriched" id="my-form">
  <!-- The SDK injects both automatically: -->
  <input type="hidden" name="monocle"    value="eyJ..." /> // network
  <input type="hidden" name="sentinel_fp" value="a1b2..." /> // device
</form>

SDK laadimine ja tokenite genereerimine võtab ~1–2 sekundit. Kui seadmekiht ei saa töötada (nt karastatud brauser blokeerib selle), jätkub hindamine ainult võrgukihil.

Vormi saatmisel kutsu Sentinel.collect() — see ootab, kuni seadmekiht on paigas (kõige rohkem 5 sekundit; collect({ timeout: ms }) muudab seda), ja tagastab { token, fingerprintEventId }. Edasta mõlemad oma taustsüsteemi. (Või loe otse peidetud välju monocle ja sentinel_fp.) Kliendipoolselt renderdatud rakendus (React, Next.js, Vue)? Midagi lisada pole vaja: skript hoiab ise ühte peidetud vormi, nii et token on olemas ka vormidele, mille sinu rakendus renderdab pärast lehe laadimist.

document.getElementById('my-form').addEventListener('submit', async (e) => {
  e.preventDefault();

  // Both layers: network token + device event id
  const { token, fingerprintEventId } = await window.Sentinel.collect();

  if (!token) {
    // Network SDK still loading — ask user to try again
    return showError('Security check loading. Please try again.');
  }

  // Forward both to your backend with the rest of the form data
  const res = await fetch('/your-backend-endpoint', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      email: e.target.email.value,
      token, fingerprintEventId  // ← both layers to your backend
    })
  });
});

Sinu sait saadab Content-Security-Policy päise? Lisa oma direktiividele SDK enda hostid: script-src https://maskbreak.com https://mcl.maskbreak.com https://*.mcl.maskbreak.com https://mesu.maskbreak.com 'wasm-unsafe-eval', connect-src https://mcl.maskbreak.com https://*.mcl.maskbreak.com wss://mcl.maskbreak.com wss://*.mcl.maskbreak.com https://mesu.maskbreak.com ja worker-src https://mesu.maskbreak.com blob:. Osa, mille poliitika blokeerib, jääb tühjaks ja kontroll jätkub ilma selleta.

Kutsu seda oma taustsüsteemi serverist — mitte kunagi brauserist. Edasta kliendilt saadud token ja oma salajane API-võti.

Päringu keha

Testimine ilma brauserita: saada deterministlik testtoken — test_clean, test_vpn, test_proxy, test_datacenter või test_tor —, et oma allow / review / block käsitlust otsast otsani proovida. Testpäringud autenditakse ja piiratakse sagedusega nagu päris omad, aga neid ei arvestata, salvestata ega saadeta veebihaakidesse, ja vastus kannab "test": true.

CI & staging ilma kontota: avalik liivakastivõti sk_test_sandbox aktsepteerib samu test_* tokeneid ja tagastab samad deterministlikud kujud — ilma registreerumiseta, midagi ei arvestata, midagi ei salvestata, päris kvooti ei puudutata kunagi. See vastab ainult testtokenitele (reaalliiklus vajab ikka sinu päris võtit) ja on IP kohta piiratud sagedusega. curl -X POST https://maskbreak.com/v1/evaluate -H "Authorization: Bearer sk_test_sandbox" -H "Content-Type: application/json" -d '{"token":"test_vpn"}'

Sinu enda testvõti (täiskonveier): igal kontol on ka isiklik sk_test_… võti (Seaded → API võtmed), mis erinevalt liivakastist jooksutab kogu reaalajakonveierit — päris tokenid, päris seadmeanalüüs, sinu reeglid ja erandikinnitused kaasa arvatud. Selle loodud sündmused on konsoolis märgitud testina, statistikast välja jäetud, ei käivita kunagi veebihaake, ja vastus kannab "test": true. Selle kontrollid lähevad nagu konsooli enda kontrollidki sinu kuu mahu hulka; ülal toodud fikseeritud testtokenid mitte. Sellel on oma tunnilimiit ja see on sihilikult IP-lubamisnimekirjast vabastatud, et CI ja sülearvutid saaksid konveierit proovida ilma su tootmispiirangusse auke löömata.

const response = await fetch('https://maskbreak.com/v1/evaluate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    token: req.body.token,   // as sent by your frontend (see Quick Start Step 2)
    fingerprintEventId: req.body.fingerprintEventId,
    tz: req.body.tz
  })
});

const data = await response.json();
// data.decision → 'allow' | 'review' | 'block' (covers VPN, proxy,
// datacenter, Tor, antidetect, automation) — route on this
// data.reasons  → machine-readable why

if (data.decision === 'block') {
  return res.status(403).json({ error: 'Suspicious connection.' });
}

# pip install sentinelsup
from sentinel import Sentinel

s = Sentinel(api_key='sk_live_YOUR_API_KEY')  # or omit — reads SENTINEL_KEY env var

# request_body is the JSON body parsed by your web framework.
# This SDK requires a non-empty token; use raw HTTP for degraded fallback or tz.
result = s.evaluate(
    token=request_body.get('token', ''),
    fingerprint_event_id=request_body.get('fingerprintEventId')
)

# result.decision → 'allow' | 'review' | 'block' — route on this
# result.reasons  → machine-readable why

if result.is_blocked:
    return '403 Suspicious connection', 403

curl -X POST 'https://maskbreak.com/v1/evaluate' \
  -H 'Authorization: Bearer sk_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"token": "YOUR_BROWSER_TOKEN", "fingerprintEventId": "YOUR_DEVICE_EVENT", "tz": "Europe/Tallinn"}'

// composer require sentinelsup/sdk
$sentinel = new \Sentinel\Client();  // or pass the key — reads SENTINEL_KEY env var

// The frontend sends JSON, not a URL-encoded form.
// This SDK requires a non-empty token; use raw HTTP for degraded fallback or tz.
$input = json_decode(file_get_contents('php://input'), true, 512, JSON_THROW_ON_ERROR);
$result = $sentinel->evaluate([
    'token' => $input['token'] ?? '',
    'fingerprintEventId' => $input['fingerprintEventId'] ?? null,
]);

// $result->decision → 'allow' | 'review' | 'block' — route on this
// $result->reasons  → machine-readable why

if ($result->isBlocked()) {
    http_response_code(403);
    exit();
}

Saada värske päris brauserisündmus /v1/evaluate aadressile tootmisvõtmega. device.customer_history loendab ainult sinu kliendikonto viimase 90 päeva erinevaid kinnitatud sündmusi ning näitab esimest ja viimast külastust, korduvkülastuse olekut ja seotud kontode arvu. Töölaua Sündmused → Uuri kuvab 50 viimati nähtud seadet. Ajalugu koguneb pärast funktsiooni kasutuselevõttu; vanu sündmusi ei lisata tagantjärele. Sama sündmuse korduv saatmine läheb arvesse ühe korrana. Puuduv seadmetõend tähendab puuduvat ajalugu, mitte uut ega ohutut seadet.

Kontode seostamiseks peab sinu server määrama accountId enda autenditud kasutaja või seansi põhjal, mitte kopeerima brauseri väidetud kontotunnust. Kasuta pseudonüümset ID-d, mitte e-posti aadressi. Ühist seadet kasutavad kontod on taustainfo, mitte pettuse tõend. Testvõtme liiklust sellesse ajalukku ei lisata. Varasemad times_seen, returning ja first_seen väljad säilitavad jagatud loenduri tähenduse; oma külastajate jaoks kasuta customer_history välja.

// Your backend: accountId comes from YOUR authenticated session.
const response = await fetch('https://maskbreak.com/v1/evaluate', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + process.env.MASKBREAK_API_KEY,
    'Content-Type': 'application/json'
  },
  signal: AbortSignal.timeout(8000),
  body: JSON.stringify({
    token: req.body.token,
    fingerprintEventId: req.body.fingerprintEventId,
    accountId: req.user ? String(req.user.id) : undefined,
    gpuEvidence: req.body.gpuEvidence // optional beta; otherwise omit
  })
});
if (!response.ok) throw new Error('Visitor check unavailable');
const result = await response.json();
const history = result.device?.customer_history;
// history: {visits, returning, first_seen, last_seen, accounts, window_days:90}
// Use your existing decision/review policy. History is not authorization.

// 1. Your backend requests a challenge using its LIVE API key.
// Protect your own route with session/CSRF checks and rate limits.
const response = await fetch('https://maskbreak.com/v1/device-evidence/challenge', {
  method: 'POST',
  headers: { Authorization: 'Bearer ' + process.env.MASKBREAK_API_KEY,
    'Content-Type': 'application/json' },
  signal: AbortSignal.timeout(6000),
  body: JSON.stringify({ fingerprintEventId: req.body.fingerprintEventId })
});
if (!response.ok) return res.status(200).json({ status: 'unavailable' });
return res.json(await response.json()); // challenge, expires_at, protocol

// 2. Browser, after your required consent/notice flow:
// Load https://maskbreak.com/assets/device-evidence.js?v=1 separately.
// Pass the challenge from YOUR backend; never send your API key here.
const gpuEvidence = challenge
  ? await MaskbreakGPU.collect(challenge)
  : { status: 'unavailable' };
// Forward only successful evidence with the SAME fingerprintEventId:
// gpuEvidence: gpuEvidence.features ? gpuEvidence : undefined
// If unavailable or your challenge route fails, continue normal checks.

// Browser: load /assets/browser-consistency.js?v=1 from maskbreak.com.
// Run only on an opted-in review step, after required notice/consent.
// Obtain the one-use challenge from YOUR authenticated backend route above.
const browserEvidence = challenge
  ? await MaskbreakBrowserConsistency.collect(challenge)
  : { status: 'unavailable' };
// Forward to YOUR backend with the same session-bound fingerprintEventId.
// Do not expose a Maskbreak API key in browser code.

// Backend: optional field in the existing POST /v1/evaluate JSON body:
// browserEvidence: browserEvidence.protocol ? browserEvidence : undefined
// Send either browserEvidence OR gpuEvidence for a device event, not both.
// Read result.device?.browser_consistency:
// {status:'inconsistent', experimental:true, source:'browser_reported',
//  affects_decision:false, findings:['browser_context'], checks:[...]}
// Keep the original decision/review policy. This report is not authorization.

Vastuseobjekt

Õnnestunud päring tagastab 200 OK koos selle JSON-struktuuriga.

{
  "status": "success",
  "isSuspicious": true,
  "decision": "review",
  "risk_score": 65,
  "ip": "185.107.80.12",
  "country": "EE",
  "network": {
    "vpn": true,
    "proxy": false,
    "datacenter": true,
    "tor": false,
    "anonymous": true,
    "residential": false,
    "service": "PROTON_VPN"
  },
  "reasons": ["vpn_detected", "datacenter_asn"],
  "evaluated_in_ms": 126,
  "details": {
    "ip": "185.107.80.12",
    "cc": "EE",
    "vpn": true,
    "proxied": false,
    "anon": true,
    "dch": true,
    "service": "PROTON_VPN"
  }
}

{
  "status": "success",
  "isSuspicious": false,
  "decision": "allow",
  "risk_score": 0,
  "ip": "82.131.45.9",
  "country": "DE",
  "network": {
    "vpn": false,
    "proxy": false,
    "datacenter": false,
    "tor": false,
    "anonymous": false,
    "residential": true,
    "service": null
  },
  "reasons": [],
  "evaluated_in_ms": 118
}

Kuidas otsus sünnib

Mootor tagastab proksi, Tori väljundi, tuvastatud boti, emulaatori või brauseri manipuleerimise korral block. VPN üksi või virtuaalmasinas töötav brauser annab tulemuseks review. Muud signaalid ja sinu reeglistik võivad lõppvastust mõjutada. Pilveserveri või anonüümse võrgu lipp üksi ei põhjusta kindlat blokeeringut. Sinu reeglid ja erandid võivad otsuse üle kirjutada; engine_decision lisatakse siis, kui ülekirjutus otsust muudab, mitte igale vastusele.

Piiratud teabega vastused. Võrguteabe puudumisel tagastatakse degraded: true, ip: "unknown" ja võrgulipud väärtusega false. Need false-väärtused tähendavad, et teave pole kättesaadav, mitte seda, et ühendus on puhas. Seadme- või e-posti signaalid, reeglid ja erandid võivad endiselt anda tulemuseks review või block. Hindamiste koguarvust ja sündmuste logist jäetakse välja ainult lihtne mittekahtlane allow-varuvastus; sisuliste otsuste puhul kehtib tavapärane sündmuste ja kasutusarvestuse käsitlus. Autenditud katsed kasutavad endiselt tunnist päringulimiiti.

Lisalipud. test: true igal testtokeni või testvõtme vastusel, sandbox: true, kui kasutati avalikku sk_test_sandbox võtit, sample: true otspunktil /v1/evaluate/sample. /v1/lookup kannab lisaks täiendavat network.cloud objekti, mis nimetab teenusepakkuja, kui aadress asub avaldatud pilvevahemikus.

Põhjusekoodid

Iga väärtus, mida reasons[] kanda võib, ja mida see tähendab. Uusi koode ainult lisatakse.

• anonymous_network — anonüümiv võrk ilma nimetatud operaatorita
• antidetect_browser — võltsbrauser (antidetect-tööriist või võltsitud keskkond)
• automation_detected — skript või liideseta (headless) brauser
• datacenter_asn — andmekeskuse või pilve aadress
• disposable_email — ühekordne e-posti aadress
• emulator_detected — emulaator
• high_activity_device — ebatavaliselt sageli nähtud seade (pehme signaal)
• ip_blocklisted — mustas nimekirjas olev aadress
• multi_account_device — seade, mis on juba mitme sinu konto taga
• private_browsing — inkognito- või privaataken
• proxy_detected — residentne või pilveproksi
• timezone_mismatch — brauseri ajavöönd ei klapi aadressiga (ainult kontrollimisel)
• tor_exit_node — Tori väljundsõlm
• virtual_machine — virtuaalmasinas töötav brauser (üksi: review)
• vpn_detected — VPN-teenus (network.service nimetab selle, kui teada)

Testtokenid

Saada üks neist token-ina oma tootmisvõtme, testvõtme või sk_test_sandbox-iga. Sinu enda võtmetega järgivad need sinu reegleid ja erandikinnitusi (nii on test_vpn üherealine viis reegli kontrollimiseks); neid ei arvestata kunagi. Konsoolist tehtud päringud salvestatakse testridadena, et sündmuste logil oleks midagi näidata.

IP-otsing

Otsus paljale IP-aadressile — brauseri tokenit pole vaja. Sama võti ja sama tunnilimiit mis /v1/evaluate; päringutel on oma kuulimiit, mis on paketi külastajakontrollide arv korda 10 (tasuta paketis 100 000 kuus).

curl https://maskbreak.com/v1/lookup/185.220.101.34 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

{
  "ip": "185.220.101.34",
  "known": true,
  "verdict": "block",            // allow | review | block
  "risk_score": 90,
  "signals": { "vpn": false, "proxied": false, "tor": true, "dch": false, "anon": true },
  "network": { "asn": 60729, "org": "Tor exit node", "country": null, "city": null,
               "registration_country": "DE", "source": "asn_table" },
  "latency_ms": 12
}

Kasutus

Sinu võtme kvoodiseis otspunktina — küsi seda, selle asemel et viimase vastuse päistest limiite kraapida.

curl https://maskbreak.com/v1/usage \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

{
  "key_type": "live",            // or "test"
  "plan": "free",                // free | starter | growth | scale | custom | public_interest
  "monthly_limit": 10000,
  "month_used": 2481,
  "monthly_lookup_limit": 100000,
  "month_lookups_used": 5210,
  "month_resets_at": "2026-08-01T00:00:00.000Z",  // 00:00 UTC on the 1st of next month
  "grandfathered_until": null,   // set while an account created before 1 Oct 2026 keeps its previous allowance
  "hourly_limit": 1000,
  "used_this_hour": 412,
  "remaining": 588,
  "resets_at": "2026-07-19T11:00:00.000Z",  // end of the rolling 60 minutes that began with your first call; null if nothing used yet
  "total_evaluations": 183204,
  "limit_hits": 3
}

Limiidid ja teavitused. Tunnine arvestusaken algab sinu esimese päringuga; kuulimiit järgib kalendrikuud (UTC). Omanikule saadetakse kasutushoiatus tunnilimiidi 80% juures ja selle täitumisel, tootmisvõtme puhul kõige rohkem üks kord kummagi läve kohta 24 tunni jooksul, ning kuulimiidi umbes 80% ja 100% juures. Testvõti tunnihoiatusi ei saada; selle päringud lähevad kuulimiidi sisse ja võivad seega käivitada kuulimiidi hoiatused. /v1/usage ei tarbi hindamiskvooti, kuid on piiratud 120 lugemispäringuga minutis aadressi kohta, sealhulgas avaliku huvi kontodel (429 koos Retry-After-iga). Otspunkt ei rakenda võtme IP-lubamisnimekirja; konto peatamine annab siiski vastuseks 403. Korduvad vigased autentimisandmed võivad põhjustada aadressi 15-minutilise blokeeringu (429, Retry-After: 900).

Veebihaagid

Ohuteavitused Slacki, Discordi või sinu enda otspunkti — seadistatakse konsooli Integratsiooni vahekaardil Teavituste all.

const crypto = require('crypto');
const express = require('express');
const app = express();

// Raw body required — verify the exact bytes Maskbreak signed,
// never a re-serialized JSON.parse() of them.
app.post('/webhooks/sentinel', express.raw({ type: 'application/json' }), (req, res) => {
  const secret = process.env.SENTINEL_WEBHOOK_SECRET;  // shown next to the URL in the dashboard
  const ts  = req.get('X-Maskbreak-Timestamp') || '';
  const sig = req.get('X-Maskbreak-Signature') || '';

  // Freshness: reject anything older than 5 minutes (replay defense)
  const age = Math.abs(Date.now() / 1000 - Number(ts));
  if (!ts || !Number.isFinite(age) || age > 300) return res.status(400).end();

  // "sha256=" + HMAC_SHA256(secret, timestamp + "." + rawBody), hex digest
  const expected = 'sha256=' + crypto.createHmac('sha256', secret)
    .update(ts + '.').update(req.body).digest('hex');

  // Constant-time compare — never ===
  const a = Buffer.from(sig), b = Buffer.from(expected);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.status(401).end();
  }

  const event = JSON.parse(req.body);  // { event: "threat.detected", event_id, ip, threat_type, details }
  // ... handle it (queue it, alert, block the IP upstream)
  res.status(200).end();  // answer 2xx fast — deliveries time out after 10 s
});

import hashlib, hmac, os, time
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ["SENTINEL_WEBHOOK_SECRET"].encode()  # shown next to the URL in the dashboard

@app.post("/webhooks/sentinel")
def sentinel_webhook():
    ts  = request.headers.get("X-Maskbreak-Timestamp", "")
    sig = request.headers.get("X-Maskbreak-Signature", "")

    # Freshness: reject anything older than 5 minutes (replay defense)
    try:
        fresh = abs(time.time() - int(ts)) <= 300
    except ValueError:
        fresh = False
    if not fresh:
        abort(400)

    # "sha256=" + HMAC_SHA256(secret, timestamp + "." + raw_body), hex digest.
    # Sign request.get_data() — the exact raw bytes, not request.json.
    expected = "sha256=" + hmac.new(
        SECRET, ts.encode() + b"." + request.get_data(), hashlib.sha256
    ).hexdigest()

    # Constant-time compare — never ==
    if not hmac.compare_digest(sig, expected):
        abort(401)

    event = request.get_json(force=True)  # {"event": "threat.detected", "event_id": ..., "ip": ..., "details": ...}
    # ... handle it (queue it, alert, block the IP upstream)
    return "", 200

{
  "event": "threat.detected",
  "event_id": "9f2ce7a4c1d84b7fa3d2c05e8b6f4a19",  // unique per event; same on retries
  "timestamp": "2026-07-19T09:14:03.512Z",
  "ip": "185.220.101.34",
  "threat_type": "Tor",              // or "Custom rule (…)" / "Customer exception (…)"
  "details": {
    "ip": "185.220.101.34", "cc": "DE",
    "vpn": false, "proxied": false, "tor": true, "dch": false,
    "bot": false, "tampering": false, "antidetect": false,
    "virtual_machine": false,        // since 29 Sep 2026; tampering = tampered browser or emulator
    "decision": "block",
    "rule_matched": null,            // signals, when your rule caused the block
    "exception_matched": null        // pins, when your exception caused it
  }
}

MCP AI-agentidele

Hallatud Model Context Protocoli server — suuna AI-agent sellele ja ta saab IP-sid päris Maskbreaki otsustega kontrollida.

{
  "mcpServers": {
    "sentinel": {
      "type": "http",
      "url": "https://maskbreak.com/mcp",
      "headers": { "Authorization": "Bearer sk_live_YOUR_API_KEY" }
    }
  }
}

API stabiilsus & versioonimine

Millele saad ehitada, muretsemata, et pind liigub.