QueryShieldquery-intel.com
Ouvrir un acces

Documentation API

Toutes les capacites du produit sont exposees par API. Les endpoints d analyse sont disponibles sur l offre gratuite dans la limite du quota quotidien ; au-dela, une cle de licence est requise dans l en-tetex-qs-license.

Authentification

curl -X POST https://queryshield.query-intel.com/api/analyze \
  -H "content-type: application/json" \
  -H "x-qs-license: VOTRE_CLE" \
  -d '{"text":"Votre colis est bloque : http://exemple.top/x","channel":"sms"}'

Sans cle de licence, la requete est rattachee a un identifiant anonyme depose en cookie et soumise au quota de l offre Decouverte.

POST/api/analyzeAnalyser un message

Requete

{
  "text": "Votre colis est bloque, reglez les frais sous 24h : http://exemple.top/x",
  "channel": "sms",
  "subject": "optionnel, e-mail uniquement",
  "rawHeaders": "optionnel, en-tetes bruts de l e-mail",
  "sender": "optionnel, adresse de l expediteur"
}

Reponse

{
  "score": 91,
  "verdict": "dangerous",
  "confidence": 0.84,
  "summary": "Score de risque 91/100 : le message est tres probablement frauduleux.",
  "findings": [
    {
      "id": "url-brand-impersonation",
      "category": "identite",
      "severity": "high",
      "title": "Domaine usurpant une marque connue",
      "detail": "Le domaine reprend le nom d une marque...",
      "evidence": "hxxp://chronopost-livraison-suivi[.]top/frais-colis",
      "weight": 20,
      "sources": ["heuristique"]
    }
  ],
  "iocs": {
    "urls": ["http://chronopost-livraison-suivi.top/frais-colis"],
    "domains": ["chronopost-livraison-suivi.top"],
    "emails": [],
    "phones": [],
    "ibans": [],
    "crypto": [],
    "files": []
  },
  "signals": { "critical": 0, "high": 3, "medium": 4, "low": 1, "info": 0 },
  "categories": [{ "category": "lien", "score": 47, "findings": 4 }],
  "recommendations": ["Ne cliquez sur aucun lien..."],
  "quota": { "used": 1, "limit": 10, "remaining": 9 },
  "plan": "free"
}
  • Le champ `text` est obligatoire (4 caracteres minimum, 20 000 maximum).
  • `channel` accepte : email, sms, messaging, unknown.
  • Le contenu recu n est ni stocke, ni journalise, ni transmis a un tiers publicitaire.
  • Les liens presents dans le message ne sont jamais ouverts ni resolus par le moteur.
POST/api/check-siteVerifier l authenticite d un site

Requete

{
  "url": "credit-agricole-securite.xyz",
  "active": false
}

Reponse

{
  "verdict": "phishing",
  "score": 79,
  "confidence": 0.55,
  "officialBrand": null,
  "impersonatedBrands": ["Credit Agricole"],
  "identity": { "host": "credit-agricole-securite.xyz", "registrable": "credit-agricole-securite.xyz", "tld": "xyz" },
  "findings": [
    {
      "id": "site-impersonates-brand",
      "severity": "critical",
      "title": "Ce site se fait passer pour une organisation connue",
      "params": { "brands": "Credit Agricole" }
    }
  ],
  "recommendations": [
    { "id": "site-rec-no-credentials", "text": "Ne saisissez ni identifiant, ni mot de passe..." }
  ],
  "network": null,
  "meta": { "active": false, "siteContacted": false }
}
  • Le site analyse n est JAMAIS ouvert ni contacte : toutes les verifications sont statiques.
  • `active: true` interroge en plus l annuaire des domaines (RDAP) et la reputation du site. Le nom de domaine est alors transmis a ces services tiers.
  • `verdict` vaut : official, unknown, suspicious ou phishing.
  • `unknown` signifie « rien de suspect, mais rien ne confirme non plus » : ce n est pas une validation.
  • Les adresses de reseau interne et les plages privees sont refusees (400).
GET/api/healthEtat du service

Reponse

{
  "status": "ok",
  "service": "queryshield",
  "engine": "queryshield-heuristic",
  "version": "0.1.0",
  "semanticEngine": "absent (heuristiques seules)",
  "billing": "absent"
}
  • Utile pour les sondes de supervision et les integrations CI.
POST/api/billing/checkoutOuvrir une session de paiement

Requete

{
  "plan": "pro",
  "interval": "monthly"
}

Reponse

{ "url": "https://checkout.stripe.com/c/pay/cs_test_..." }
  • Repond 501 tant que STRIPE_SECRET_KEY et les identifiants de prix ne sont pas configures.
  • L appelant doit rediriger l utilisateur vers l URL renvoyee.
POST/api/billing/webhookRecevoir les evenements Stripe

Requete

corps brut envoye par Stripe

Reponse

{ "received": true, "event": "checkout.session.completed" }
  • La signature `stripe-signature` est verifiee en HMAC-SHA256 avec tolerance de 300 secondes.
  • Aucune re-serialisation du corps : la verification porte sur les octets bruts.

Codes d erreur

400 missing_text
Le champ text est absent ou trop court.
400 missing_url
Aucune adresse de site n a ete fournie.
400 invalid_url
Adresse inexploitable, ou hote interne / plage privee refuse par le garde-fou SSRF.
400 invalid_json
Le corps de la requete n est pas un JSON valide.
413 payload_too_large
Corps de requete au-dela de la limite annoncee.
429 rate_limited
Trop de requetes depuis la meme origine.
429 quota_exceeded
Quota quotidien de l offre atteint.
501 billing_not_configured
La facturation n est pas activee sur cette instance.
502 stripe_error
Stripe a refuse la creation de la session.

Comprendre le score

  • 0 a 27 — risque faible. Aucun signal fort. Le message peut toutefois contenir des elements hors du perimetre de l analyse statique.
  • 28 a 59 — suspect. Au moins un signal notable. Verifiez aupres de l organisme concerne avant toute action.
  • 60 a 100 — fraude probable. Plusieurs signaux convergent, ou un signal critique est present. Ne cliquez sur rien et n envoyez aucune donnee.

Le score est calcule par une courbe logarithmique sur la somme des poids, puis releve par des regles de decision explicites (deux signaux critiques, trois signaux forts, convergence de trois familles de signaux). Le champ `confidence` mesure la qualite du signal disponible, pas la certitude du verdict.

Documentation API · QueryShield