Référence de l'API

Démarrage rapide

Créez un site dans le portail Ironfang (en anglais), ou directement via l'API. L'ID de site renvoyé sert à ajouter des règles et à lancer des audits.

curl -X POST https://api.ironfang.uk/audit/v1/sites \
              -H "Authorization: Bearer $IRONFANG_ACCESS_TOKEN" \
              -H "Content-Type: application/json" \
              -d '{
                "name": "Acme Finance",
                "url": "https://www.example.com"
              }'

Toute l'API existe aussi sous forme de collection Postman publique, générée à partir du contrat OpenAPI. Son dossier Getting started crée un site, déclenche un audit et en suit l'état ; la première requête ne demande aucune clé.

Exécuter dans PostmanVoir la collection

Clés API

Une automatisation peut utiliser une clé API de la plateforme au lieu d'un jeton utilisateur : créez-la dans le portail avec les portées Ironfang Audit dont elle a besoin et envoyez-la comme jeton bearer. Une clé n'agit que dans l'organisation pour laquelle elle a été créée, et chaque portée correspond à une permission : audit:read, audit:run, audit:manage, audit:evidence, audit:integrations, ou audit:* pour toutes. Une clé sans portée Ironfang Audit est refusée avec 403 insufficient_scope.

Règles déterministes

Les règles conservent leur version exacte dans chaque résultat. Les bases prises en charge incluent : le texte contient ou ne contient pas, les expressions régulières, la présence et le texte d'éléments, les liens, les métadonnées, le statut HTTP, HTTPS et les en-têtes de réponse.

{
              "name": "Company number is present",
              "rule_type": "text_contains",
              "severity": "failure",
              "configuration": { "value": "12764014" }
            }

Une défaillance du robot d'exploration est un état opérationnel de la preuve, pas l'échec d'une règle de conformité.

Cycle de vie d'un audit

Les audits sont asynchrones. Utilisez l'ID d'audit permanent renvoyé pour interroger la ressource, ou consommez les webhooks de cycle de vie signés par HMAC. Les exports S3 et la livraison des webhooks réessaient indépendamment de la finalisation des preuves.

Chaîne de preuves

Chaque manifeste de page contient les hachages de sa capture d'écran brute, du HTML, du texte visible, des en-têtes et des métadonnées réseau. Les hachages des pages deviennent des feuilles de Merkle à séparation de domaine. Ironfang Audit signe le manifeste d'audit canonique avec Ed25519 et soumet le hachage racine de l'audit, et non le contenu du site, à une autorité d'horodatage RFC 3161.

Les captures brutes restent immuables. Les tuiles de capture d'écran et les rapports sont des dérivés de présentation dont la provenance est indiquée.

POST /verify/v1/bundles

Importez un ZIP de preuves avec Content-Type: application/zip, ou vérifiez-le entièrement hors ligne avec le vérificateur en ligne de commande.

ironfang audit verify -bundle evidence.zip \
              -trusted-public-key audit-ed25519.pub \
              -tsa-ca tsa-chain.pem

Le vérificateur recalcule les hachages des artefacts, valide l'appartenance de chaque page à l'arbre de Merkle et contrôle la signature d'Ironfang Audit à l'aide d'une clé de signature approuvée de manière indépendante. Avec une AC TSA de confiance configurée, il valide aussi la réponse RFC 3161. La clé intégrée à un ZIP n'est jamais acceptée comme sa propre ancre de confiance.

Des builds pour Linux, macOS et Windows sont publiés sous licence Apache 2.0. Chaque version publiée inclut des sommes de contrôle et une provenance de build Sigstore signée.

GET /v1/sites

Liste tous les sites Ironfang Audit disponibles pour l'organisation courante.

POST /v1/sites

Enregistre un site web public et son périmètre d'exploration. La réponse contient l'ID de site permanent utilisé par les règles et les audits.

GET /v1/sites/{siteId}

Renvoie un site et sa politique d'exploration actuelle.

GET /v1/sites/{siteId}/rules

Liste les règles déterministes versionnées configurées pour un site.

POST /v1/sites/{siteId}/rules

Crée la première version immuable d'une règle déterministe.

GET /v1/audits

Liste les audits de l'organisation courante. Passez site_id en paramètre de requête pour limiter la réponse à un site.

POST /v1/sites/{siteId}/audits

Met en file d'attente un audit asynchrone. Envoyez un en-tête Idempotency-Key lorsqu'un client peut réessayer la requête.

GET /v1/audits/{auditId}

Interroge le statut de l'audit, son état de conformité, le nombre de pages et le hachage racine des preuves.

GET /v1/audits/{auditId}/pages

Liste les observations de pages capturées, les résultats des règles et la classification des modifications.

GET /v1/audits/{auditId}/evidence

Télécharge le ZIP de preuves vérifiable de manière indépendante une fois que l'audit a atteint completed ou partial. La réponse est de type application/zip.

GET /v1/artifacts/{artifactId}

Diffuse un artefact de preuve propre au locataire, avec son type de média enregistré.

GET /verify/v1/signing-keys

Renvoie le registre public des clés de signature utilisé par le vérificateur hébergé.

GET /v1/sites/{siteId}/monitors

Liste les moniteurs d'un site : ce qui est surveillé, à quelle fréquence, et quand la prochaine exécution est prévue.

POST /v1/sites/{siteId}/monitors

Crée un moniteur. mode vaut full_site (exploration) ou url_set (les pages de urls) ; cadence vaut manual, daily, six_hourly ou hourly, dans la limite de l'offre ; anchor_minute et timezone fixent le créneau quotidien. Chaque exécution planifiée est un audit complet, avec la même chaîne de preuves qu'un audit manuel.

La politique façonne la comparaison et la notification, jamais l'enregistrement : la capture d'écran brute, le HTML et le texte visible sont stockés intacts, et le texte normalisé est conservé à côté en tant que dérivé.

POST /v1/monitors/{monitorId}/run

Exécute le moniteur immédiatement. /pause, /resume et /archive changent le statut ; PUT /urls remplace l'ensemble de pages ; GET /runs liste les audits produits par le moniteur.

GET /v1/page-observations/{observationId}/comparison

Ce qui a changé par rapport à la capture précédente, calculé à partir des preuves stockées selon la politique de modification de l'audit : blocs de texte normalisé avec numéros de ligne, scores textuel et visuel, changements d'URL, de titre et de statut HTTP, résultats de règles qui ont changé, ID des artefacts de capture d'écran des deux côtés, et caractère significatif ou non de la modification. Une première capture n'a pas de côté précédent et en indique la raison.

GET /v1/pages/{pageId}/observations

L'historique d'une page d'un audit à l'autre, du plus récent au plus ancien. limit jusqu'à 200 ; passez le next_cursor renvoyé pour continuer.

GET /v1/audits/{auditId}/pages?change=changed&compliance=fail

La liste des pages accepte change (new, changed, moved, unchanged), compliance (pass, fail, error), capture (captured, failed) et q (sous-chaîne de l'URL ou du titre) ; chacun est une liste séparée par des virgules. total est le nombre non filtré.

GET /v1/events

Les événements récents de l'organisation (audit.started, audit.completed, audit.partial, audit.failed, change.detected, compliance.failed, monitor.skipped, quota.threshold_reached), avec la charge utile reçue par chaque webhook. Les enveloppes de webhook portent schema_version et l'ID de l'événement comme clé d'idempotence ; un endpoint est désactivé après 20 échecs consécutifs et réactivé avec PATCH /v1/webhooks/{endpointId} (enabled, events). DELETE retire un endpoint et conserve son historique ; POST .../deliveries/{deliveryId}/retry remet une livraison en file d'attente.

GET /v1/notification-preferences

Quels événements sont envoyés par e-mail, à qui, et s'ils partent immédiatement ou dans un récapitulatif quotidien (07:00 UTC). PUT avec events, recipients et digest ; les destinataires doivent être des membres actuels de l'organisation, et une clé API peut conserver la liste mais pas la modifier. Les e-mails contiennent des chiffres et un lien vers le portail, jamais de contenu capturé. GET /v1/notifications est le journal des envois.

GET /v1/webhooks

Liste les endpoints de webhook enregistrés pour l'organisation courante.

POST /v1/webhooks

Enregistre un endpoint HTTPS public. Le secret de signature HMAC est renvoyé une seule fois, dans la réponse de création.

GET /v1/export-destinations

Liste les destinations de preuves S3 et compatibles S3 configurées.

POST /v1/export-destinations

Crée une destination S3 chiffrée. Les champs obligatoires sont region, bucket, access_key et secret_key. Les champs facultatifs incluent endpoint, prefix, path_style, session_token et export_mode.

POST /v1/audits/{auditId}/exports

Met en file d'attente l'export d'un audit terminé vers la destination_id fournie.

GET /v1/usage

Renvoie le total des pages capturées, des audits et des crédits de capture de page consommés par l'organisation, ainsi que l'offre qui s'applique à elle (le même catalogue que /v1/plans), pour qu'un client sache à l'avance quelles fréquences et combien de sites sont autorisés.

GET /v1/plans

Renvoie le catalogue des offres : prix en pence, crédits mensuels, limite de sites, fréquence minimale, conservation hébergée en jours et ouverture ou non du paiement. Sans authentification ; ce sont les mêmes données que celles qui servent à vérifier la page des tarifs.

Erreurs

Chaque erreur renvoyée par une opération a la même forme JSON : un code stable, un message destiné aux personnes, un lien vers cette section et l'ID de la requête.

{
  "error": {
    "code": "evidence_not_final",
    "message": "the evidence bundle is available after evidence finalisation",
    "docs": "https://ironfang.uk/audit/docs#errors"
  },
  "request_id": "01a0c375-6b34-7c1e-9b52-4f0a8d3e6c17"
}

Basez votre logique sur code et le statut HTTP : le code est stable et lisible par machine, tandis que message est rédigé pour les personnes et peut changer. De nouveaux codes peuvent être ajoutés ; traitez un code inconnu selon sa classe de statut. docs renvoie vers cette section. request_id reprend l'en-tête de réponse X-Ironfang-Request-ID ; communiquez-le au support et nous retrouverons la requête exacte.

Cette liste n'est pas exhaustive. Un 422 n'a pas de corps d'erreur : POST /verify/v1/bundles répond à un ZIP de preuves non valide par le rapport de vérification lui-même.

Interfaces pour machines

Lancé sous le nom Auditwolf. Ce nom ne subsiste que dans des identifiants de compatibilité : l'alias de chemin d'API https://api.ironfang.uk/auditwolf, le préfixe de scope auditwolf: et les identifiants ci-dessous continuent de fonctionner et sont des alias des noms actuels.

• En-têtes de webhook Auditwolf-Signature, Auditwolf-Timestamp et Auditwolf-Event-Id
• User-Agent du robot Auditwolf-Spiderwolf/1.0
• Préfixe par défaut des clés d'export auditwolf/
• La valeur de produit auditwolf dans le catalogue des offres servi à /audit/v1/plans