API-Referenz

Schnellstart

Legen Sie eine Website im Ironfang-Portal (auf Englisch) an, oder direkt über die API. Die zurückgegebene Website-ID verwenden Sie, wenn Sie Regeln hinzufügen und Audits starten.

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"
              }'

Die gesamte API gibt es auch als öffentliche Postman-Collection, erzeugt aus dem OpenAPI-Vertrag. Ihr Ordner Getting started legt eine Website an, startet ein Audit und fragt seinen Stand ab; die erste Anfrage braucht keinen Schlüssel.

In Postman ausführenCollection ansehen

API-Schlüssel

Automatisierungen können statt eines Benutzer-Tokens einen Plattform-API-Schlüssel verwenden: Erstellen Sie ihn im Portal mit den Berechtigungen für Ironfang Audit, die er braucht, und senden Sie ihn als Bearer-Token. Ein Schlüssel handelt nur in der Organisation, für die er erstellt wurde, und jede Berechtigung steht für eine Befugnis: audit:read, audit:run, audit:manage, audit:evidence, audit:integrations oder audit:* für alle. Ein Schlüssel ohne Berechtigung für Ironfang Audit wird mit 403 insufficient_scope abgewiesen.

Deterministische Regeln

Regeln behalten in jedem Ergebnis ihre genaue Version. Zu den unterstützten Grundlagen gehören: Text enthält oder enthält nicht, reguläre Ausdrücke, Vorhandensein und Text von Elementen, Links, Metadaten, HTTP-Status, HTTPS und Antwort-Header.

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

Ein Fehler des Crawlers ist ein betrieblicher Zustand des Nachweises, keine fehlgeschlagene Compliance-Regel.

Lebenszyklus eines Audits

Audits laufen asynchron. Fragen Sie die Ressource mit der zurückgegebenen dauerhaften Audit-ID ab, oder verarbeiten Sie HMAC-signierte Webhooks zum Lebenszyklus. S3-Exporte und die Webhook-Zustellung wiederholen Fehlversuche unabhängig vom Abschluss der Nachweise.

Nachweiskette

Jedes Seitenmanifest enthält die Hashes des unbearbeiteten Screenshots, des HTML, des sichtbaren Texts, der Header und der Netzwerkmetadaten. Die Seiten-Hashes werden zu domänengetrennten Merkle-Blättern. Ironfang Audit signiert das kanonische Audit-Manifest mit Ed25519 und übermittelt den Wurzel-Hash des Audits, nicht die Inhalte der Website, an eine Zeitstempelstelle nach RFC 3161.

Die unbearbeiteten Erfassungen bleiben unveränderlich. Screenshot-Kacheln und Berichte sind abgeleitete Darstellungen mit Herkunftsnachweis.

POST /verify/v1/bundles

Laden Sie ein Nachweis-ZIP mit Content-Type: application/zip hoch, oder prüfen Sie es vollständig offline mit dem Prüfwerkzeug für die Befehlszeile.

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

Das Prüfwerkzeug berechnet die Artefakt-Hashes neu, prüft für jede Seite die Zugehörigkeit zum Merkle-Baum und prüft die Signatur von Ironfang Audit gegen einen unabhängig als vertrauenswürdig festgelegten Signaturschlüssel. Ist eine vertrauenswürdige TSA-CA konfiguriert, prüft es auch die Antwort nach RFC 3161. Der in einem ZIP eingebettete Schlüssel wird nie als sein eigener Vertrauensanker akzeptiert.

Builds für Linux, macOS und Windows werden unter Apache 2.0 veröffentlicht. Jedes Release enthält Prüfsummen und eine signierte Build-Provenienz von Sigstore.

GET /v1/sites

Listet alle Websites in Ironfang Audit auf, die der aktuellen Organisation zur Verfügung stehen.

POST /v1/sites

Registriert eine öffentliche Website und ihre Crawl-Grenze. Die Antwort enthält die dauerhafte Website-ID, die Regeln und Audits verwenden.

GET /v1/sites/{siteId}

Liefert eine Website und ihre aktuelle Crawl-Richtlinie.

GET /v1/sites/{siteId}/rules

Listet die versionierten deterministischen Regeln auf, die für eine Website konfiguriert sind.

POST /v1/sites/{siteId}/rules

Erstellt die erste unveränderliche Version einer deterministischen Regel.

GET /v1/audits

Listet die Audits der aktuellen Organisation auf. Übergeben Sie site_id als Query-Parameter, um die Antwort auf eine Website zu beschränken.

POST /v1/sites/{siteId}/audits

Stellt ein asynchrones Audit in die Warteschlange. Senden Sie einen Header Idempotency-Key, wenn ein Client die Anfrage wiederholen könnte.

GET /v1/audits/{auditId}

Fragt Status, Compliance-Zustand, Seitenzahlen und den Wurzel-Hash der Nachweise eines Audits ab.

GET /v1/audits/{auditId}/pages

Listet erfasste Seitenbeobachtungen, Regelergebnisse und die Einstufung der Änderungen auf.

GET /v1/audits/{auditId}/evidence

Lädt das unabhängig prüfbare Nachweis-ZIP herunter, sobald das Audit completed oder partial erreicht hat. Die Antwort ist application/zip.

GET /v1/artifacts/{artifactId}

Streamt ein einzelnes, mandantenbezogenes Nachweisartefakt mit seinem aufgezeichneten Medientyp.

GET /verify/v1/signing-keys

Liefert das öffentliche Verzeichnis der Signaturschlüssel, das das gehostete Prüfwerkzeug verwendet.

GET /v1/sites/{siteId}/monitors

Listet die Monitore einer Website auf: was überwacht wird, wie oft und wann der nächste Lauf fällig ist.

POST /v1/sites/{siteId}/monitors

Erstellt einen Monitor. mode ist full_site (Crawl) oder url_set (die Seiten in urls); cadence ist manual, daily, six_hourly oder hourly, begrenzt durch den Tarif; anchor_minute und timezone legen den täglichen Zeitpunkt fest. Jeder geplante Lauf ist ein vollständiges Audit mit derselben Nachweiskette wie ein manuelles.

Die Richtlinie bestimmt den Vergleich und die Benachrichtigung, nie die Aufzeichnung: Der unbearbeitete Screenshot, das HTML und der sichtbare Text werden unverändert gespeichert, und der normalisierte Text wird als abgeleitete Fassung daneben aufbewahrt.

POST /v1/monitors/{monitorId}/run

Startet sofort einen Lauf. /pause, /resume und /archive ändern den Status; PUT /urls ersetzt die Seitenmenge; GET /runs listet die Audits auf, die der Monitor erzeugt hat.

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

Was sich gegenüber der vorherigen Erfassung geändert hat, berechnet aus den gespeicherten Nachweisen nach der Änderungsrichtlinie des Audits: normalisierte Textabschnitte mit Zeilennummern, Text- und Bildwerte, Änderungen an URL, Titel und HTTP-Status, geänderte Regelergebnisse, die IDs der Screenshot-Artefakte beider Vergleichsseiten und ob die Änderung wesentlich war. Eine erste Erfassung hat keine vorherige Vergleichsseite und nennt den Grund.

GET /v1/pages/{pageId}/observations

Der Verlauf einer Seite über Audits hinweg, die neuesten zuerst. limit bis 200; übergeben Sie den zurückgegebenen next_cursor, um fortzufahren.

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

Die Seitenliste akzeptiert change (new, changed, moved, unchanged), compliance (pass, fail, error), capture (captured, failed) und q (Teilzeichenfolge von URL oder Titel); jeder Parameter ist eine kommagetrennte Liste. total ist die ungefilterte Anzahl.

GET /v1/events

Die letzten Ereignisse der Organisation (audit.started, audit.completed, audit.partial, audit.failed, change.detected, compliance.failed, monitor.skipped, quota.threshold_reached) mit der Nutzlast, die jeder Webhook erhalten hat. Webhook-Umschläge enthalten schema_version und die Ereignis-ID als Idempotenzschlüssel; ein Endpunkt wird nach 20 aufeinanderfolgenden Fehlschlägen deaktiviert und mit PATCH /v1/webhooks/{endpointId} (enabled, events) wieder aktiviert. DELETE legt einen Endpunkt still und behält seinen Verlauf; POST .../deliveries/{deliveryId}/retry stellt eine Zustellung erneut in die Warteschlange.

GET /v1/notification-preferences

Welche Ereignisse per E-Mail verschickt werden, an wen und ob sofort oder als eine tägliche Zusammenfassung (07:00 UTC). PUT mit events, recipients und digest; Empfänger müssen aktuelle Mitglieder der Organisation sein, und ein API-Schlüssel darf die Liste beibehalten, aber nicht ändern. E-Mails enthalten Zahlen und einen Link ins Portal, nie erfasste Inhalte. GET /v1/notifications ist das Versandprotokoll.

GET /v1/webhooks

Listet die Webhook-Endpunkte auf, die für die aktuelle Organisation registriert sind.

POST /v1/webhooks

Registriert einen öffentlichen HTTPS-Endpunkt. Das HMAC-Signaturgeheimnis wird einmalig in der Antwort auf die Erstellung zurückgegeben.

GET /v1/export-destinations

Listet die konfigurierten Nachweisziele in S3 und S3-kompatiblem Speicher auf.

POST /v1/export-destinations

Erstellt ein verschlüsseltes S3-Ziel. Pflichtfelder sind region, bucket, access_key und secret_key. Zu den optionalen Feldern gehören endpoint, prefix, path_style, session_token und export_mode.

POST /v1/audits/{auditId}/exports

Stellt ein abgeschlossenes Audit mit der übergebenen destination_id zum Export in die Warteschlange.

GET /v1/usage

Liefert die Gesamtzahl der erfassten Seiten, der Audits und der für Seitenerfassungen verbrauchten Credits der Organisation sowie den Tarif, der für sie gilt (aus demselben Katalog wie /v1/plans), sodass ein Client vorab erkennen kann, welche Zeitpläne und wie viele Websites erlaubt sind.

GET /v1/plans

Liefert den Tarifkatalog: Preis in Pence, monatliche Credits, Website-Limit, kürzestes Zeitplanintervall, gehostete Aufbewahrung in Tagen und ob der Checkout geöffnet ist. Keine Authentifizierung; es sind dieselben Daten, gegen die die Preisseite geprüft wird.

Fehler

Jeder Fehler, den eine Operation zurückgibt, hat dieselbe JSON-Form: einen stabilen Code, eine Meldung für Menschen, einen Link auf diesen Abschnitt und die Anfrage-ID.

{
  "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"
}

Verzweigen Sie anhand von code und dem HTTP-Status: Der Code ist stabil und maschinenlesbar, während message für Menschen geschrieben ist und sich ändern kann. Neue Codes können hinzukommen; behandeln Sie einen unbekannten Code nach seiner Statusklasse. docs verweist auf diesen Abschnitt. request_id wiederholt den Antwort-Header X-Ironfang-Request-ID; nennen Sie ihn dem Support, dann finden wir genau diese Anfrage.

Die Liste ist nicht vollständig. Ein 422 hat keinen Fehlerinhalt: POST /verify/v1/bundles beantwortet ein ungültiges Nachweis-ZIP mit dem Prüfbericht selbst.

Maschinenschnittstellen

Gestartet als Auditwolf. Dieser Name lebt nur in Kompatibilitätskennungen weiter: Der API-Pfad-Alias https://api.ironfang.uk/auditwolf, das Scope-Präfix auditwolf: und die folgenden Kennungen funktionieren weiter und sind Aliasse der aktuellen Namen.

• Webhook-Header Auditwolf-Signature, Auditwolf-Timestamp und Auditwolf-Event-Id
• Crawler-User-Agent Auditwolf-Spiderwolf/1.0
• Standard-Präfix für Exportschlüssel auditwolf/
• der Produktwert auditwolf im Tarifkatalog unter /audit/v1/plans