Naar de inhoud
HackIndex Ladon
Menu

API

Alle docs

Met de Ladon-API zoek je in de catalogus, beheer je watches, projecten en kanalen, lees je het bezorglog en haal je events op. Alles is JSON over HTTPS. Elk endpoint, veld en antwoord staat in de referentie.

De API hoort bij de betaalde abonnementen. Tokens van een team met het gratis abonnement krijgen 402 met het type plan-feature, en werken weer na een upgrade.

Adres

https://ladon.hackindex.io/api/v1

Alle paden op deze pagina zijn relatief aan dat adres, dus GET /me betekent GET https://ladon.hackindex.io/api/v1/me.

Tokens

Maak een token aan op het tabblad API van een team in Ladon.

  • Een token hoort bij jou en bij één team. Het kan nooit meer dan je rol in dat team toestaat.
  • Het wordt één keer getoond, bij het aanmaken. Ladon bewaart alleen een hash. Tokens beginnen met hi_ladon_, zodat secret-scanners een gelekt token herkennen.
  • Voor je een token maakt, bevestig je in je HackIndex-account dat jij het bent: met een passkey, je wachtwoord, een code uit je authenticator-app of een gemailde code. Je komt direct terug en hebt dan 15 minuten. Je krijgt ook een mail bij elk nieuw token.
  • Kies wanneer het verloopt: over 30 dagen, 90 dagen, een jaar of nooit.
  • Het tabblad API toont de verzoeken van de laatste 30 dagen: per dag, het aandeel fouten en de drukste endpoints, en per token hoe vaak het gebruikt is. Ladon telt per uur en endpoint, niet elk verzoek, en bewaart de tellingen 90 dagen.
  • Het werkt niet meer als je het intrekt, als het verloopt, als je het team verlaat of alleen nog de facturatie doet, en als het team tweestapsverificatie verplicht en je account die niet heeft.

Stuur het mee in de header Authorization:

curl https://ladon.hackindex.io/api/v1/me \
  -H "Authorization: Bearer $LADON_TOKEN"

Scopes

Een token doet alleen wat de scopes toestaan. Kies er zo min mogelijk.

Scope Staat toe Vereist
software:read Zoeken in de catalogus
vulnerabilities:read Kwetsbaarheden lezen
watches:read Watches lezen
watches:write Watches toevoegen, wijzigen, verwijderen
projects:read Projecten en hun rapporten lezen
projects:write Projecten toevoegen en lockfiles sturen
rules:read CVE-regels en hun matches lezen
rules:write CVE-regels toevoegen, wijzigen en verwijderen
cves:read CVE's lezen en doorzoeken
endpoints:read Kanalen lezen Owner of admin
endpoints:write Kanalen toevoegen, wijzigen, verwijderen Owner of admin
deliveries:read Het bezorglog lezen Owner of admin
deliveries:write Berichten opnieuw versturen Owner of admin
events:read De events van het team ophalen Business of Enterprise

In de API heten kanalen endpoints.

Wat je kunt doen

Onderdeel Endpoints
Meta GET /me: het token, team, abonnement en de limieten
Software GET /software?search=&type=, GET /software/{type}/{slug}, GET /software/{type}/{slug}/vulnerabilities
Kwetsbaarheden GET /vulnerabilities/{id}
Watches GET /watches, POST /watches, PUT /watches, GET /watches/{id}, PATCH /watches/{id}, DELETE /watches/{id}
Projecten GET /projects, POST /projects, GET /projects/{id}, PATCH /projects/{id}, POST /projects/{id}/lockfile, POST /projects/{id}/software, DELETE /projects/{id}/software/{type}/{slug}, DELETE /projects/{id}
CVE-regels GET /rules, POST /rules, POST /rules/preview, GET /rules/{id}, PATCH /rules/{id}, DELETE /rules/{id}, GET /rules/{id}/matches, zie CVE-regels
CVE's GET /cves?search=&severity=&kev=&published_after=, GET /cves/{id}
Kanalen GET /endpoints, POST /endpoints, GET /endpoints/{id}, PATCH /endpoints/{id}, DELETE /endpoints/{id}, POST /endpoints/{id}/test, POST /endpoints/{id}/rotate-secret
Bezorglog GET /endpoints/{id}/messages, GET /messages/{id}/attempts, POST /messages/{id}/retry, POST /endpoints/{id}/recover
Events GET /events?after=

Projecten

Watches, CVE-regels en kanalen leven in een project. In antwoorden hebben ze een veld project met de publieke id van hun project, zoals prj_01JB8Z7R4M2N6P8Q0S2U4W6Y8A.

  • POST /watches, PUT /watches, POST /rules en POST /endpoints nemen een optioneel project. Laat je het weg, dan gebruikt Ladon het standaardproject van het team, dus bestaande scripts blijven werken.
  • GET /watches, GET /rules, GET /endpoints en GET /events nemen een optioneel ?project= om één project te tonen. Laat je het weg, dan krijg je elk project van het team.
  • Een kanaal krijgt alleen de meldingen van het eigen project. project_filter op kanalen bestaat niet meer en wordt genegeerd als je het meestuurt. Wil je de meldingen van meerdere projecten op één adres, voeg dan in elk project een kanaal met dat adres toe.

Een plugin volgen

curl -X POST https://ladon.hackindex.io/api/v1/watches \
  -H "Authorization: Bearer $LADON_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a9e-0d4b-4c8e-9a51-3b7e2f0c8d14" \
  -d '{"software": {"type": "plugin", "slug": "contact-form-7"}, "version_constraint": ">=5.8"}'

Noem de software met type (plugin, theme, core, npm, composer, pypi, gem, cargo, golang, maven of github) en slug. Voor pakketten is de slug de pakketnaam, zoals @angular/core, laravel/framework, django, het Go-modulepad github.com/gin-gonic/gin of de Java-groupId:artifactId org.apache.logging.log4j:log4j-core, en version_constraint gebruikt de bereiken van die taal, zie Software volgen. Een premium plugin of theme die nog niet in de catalogus staat, voeg je toe met de slug, de mapnaam in wp-content. Die blijft privé voor de teams die hem volgen, tot WordPress.org of een kwetsbaarheidsfeed hem kent. Core moet in de catalogus staan. Laat events weg voor de standaardmeldingen, en project om de watch aan het standaardproject toe te voegen. Geef tags mee, bijvoorbeeld ["client-acme"], om de meldingen naar kanalen met een passende tag_filter te sturen (zie Kanalen). Het antwoord is 201 met de watch. Iets twee keer volgen in hetzelfde project geeft 409, een vol abonnement geeft 402. Dezelfde software in een ander project is een eigen watch, en telt één keer mee voor je abonnement.

Alle watches in één keer vervangen

PUT /watches krijgt de volledige lijst van wat één project moet volgen. Noem het project in project naast watches, of laat het weg voor het standaardproject. Software in de lijst wordt toegevoegd of bijgewerkt, software die er niet in staat wordt in dat project niet meer gevolgd. Andere projecten blijven zoals ze zijn. Premium plugins en themes werken hetzelfde als bij POST /watches. Dezelfde lijst nog een keer sturen verandert niets, dus het past in een CI-job. Wil je elk pakket in een lockfile volgen, stuur die dan als project, zie hieronder.

{
    "project": "prj_01JB8Z7R4M2N6P8Q0S2U4W6Y8A",
    "watches": [
        {
            "software": { "type": "plugin", "slug": "contact-form-7" },
            "version_constraint": ">=5.8"
        },
        { "software": { "type": "theme", "slug": "twentytwentyfour" } }
    ]
}

Elk item kent software, version_constraint, events, include_informational en tags. Gepauzeerde watches blijven gepauzeerd en ernstfilters blijven zoals ze zijn. Een item zonder tags houdt de tags die de watch al heeft, een lege lijst haalt ze weg. Het antwoord bevat alle watches, en meta zegt hoeveel er created, updated en removed zijn. Een lijst kan maximaal 2000 items hebben.

Een lockfile sturen

Een project is een repository die Ladon kent aan de lockfiles. Maak er een met POST /projects, met name en de lockfile als upload in lockfile. Stuur daarna elke nieuwe lockfile naar POST /projects/{id}/lockfile. Die vervangt de lockfile van het project met dezelfde naam, de andere lockfiles van het project blijven. Een project met meer lockfiles krijgt één aanroep per lockfile:

curl -X POST https://ladon.hackindex.io/api/v1/projects/prj_01JB8Z7R4M2N6P8Q0S2U4W6Y8A/lockfile \
  -H "Authorization: Bearer $LADON_TOKEN" \
  -F "lockfile=@composer.lock"

In plaats van uploads kun je de tekst sturen in content, met de bestandsnaam in filename, en de tekst van het manifest in manifest_content. Voeg het manifest, zoals package.json of Gemfile, toe in manifest om directe en dev-afhankelijkheden uit elkaar te houden waar de lockfile dat niet doet. include_dev en tags werken bij aanmaken en met PATCH /projects/{id}. Een project kiest niet welke meldingen het stuurt, de kanalen doen dat. Projecten hebben dus geen events, severity of include_informational in hun antwoorden, en die velden worden genegeerd als je ze naar een project of naar POST /projects/{id}/software stuurt. Het antwoord bevat het project met summary en findings, zoals npm audit, zodat CI de build erop kan laten falen. Watches die projecten maken, blijven buiten de watches-endpoints.

Meldingen routeren op tag

Een kanaal met een tag_filter krijgt alleen de meldingen van watches die minstens één van die tags hebben. Een lege lijst, of het veld weglaten, betekent elke watch van het project van het kanaal.

curl -X PATCH https://ladon.hackindex.io/api/v1/endpoints/we_01JB8Z6Q3K9W7XWJ5V2N4M8T1R \
  -H "Authorization: Bearer $LADON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tag_filter": ["client-acme"]}'

Tags bestaan uit kleine letters, cijfers, punten, streepjes en underscores, maximaal 32 tekens per tag en 10 per watch of kanaal.

Mislukte meldingen opnieuw versturen

Na een storing bij jou stuurt POST /endpoints/{id}/recover met since (ISO 8601, maximaal 30 dagen geleden) elk bericht van het kanaal dat sindsdien mislukte of werd opgegeven nog een keer, binnen ongeveer 10 seconden. Tests blijven buiten beschouwing. Het antwoord is 202 met het aantal in data.requeued. Het kanaal moet aan staan, anders krijg je 409. POST /messages/{id}/retry doet hetzelfde voor één bericht. In Ladon heet dit Opnieuw versturen op de kanaalpagina.

Events ophalen

In plaats van webhooks te ontvangen, kun je om nieuwe meldingen vragen. GET /events geeft de events die op de watches van het team pasten, of met ?project= van één project, oudste eerst, in dezelfde vorm als een webhook. Geef het id van het laatste event dat je verwerkte mee als after, en limit tot 100.

curl "https://ladon.hackindex.io/api/v1/events?after=evt_01JB8Z5X2C7Q4R9T6Y3W1M0N8P" \
  -H "Authorization: Bearer $LADON_TOKEN"

meta.next_cursor is het id voor de volgende keer, meta.has_more zegt of je meteen opnieuw moet vragen. De events-API hoort bij Business en Enterprise.

Lijsten en pagina's

Lijsten geven data, links en meta met current_page, last_page, per_page en total. Vraag tot 100 items met per_page en de volgende pagina met page. Events gebruiken een cursor, zie hierboven.

Wijzigingen

PATCH wijzigt alleen de velden die je meestuurt. Stuur "paused": true of false om een watch of kanaal te pauzeren of te hervatten.

Elke POST accepteert een header Idempotency-Key van maximaal 255 tekens, bijvoorbeeld een UUID. Komt hetzelfde verzoek met dezelfde sleutel binnen 24 uur nog eens, dan krijg je het eerste antwoord terug, met de header Idempotent-Replayed: true, en gebeurt er niets dubbel. De sleutel gebruiken voor een ander verzoek is een fout.

Limieten

Elk token kan 300 verzoeken per minuut doen bij Pro en Business en 1000 bij Enterprise. Een heel team kan drie keer zoveel. Antwoorden op een geldig token hebben X-RateLimit-Limit en X-RateLimit-Remaining. Boven de limiet krijg je 429 met Retry-After in seconden.

Advisories voor pakketten veranderen elke 15 minuten en WordPress-gegevens ongeveer elk half uur, dus vaker dan om de paar minuten vragen levert zelden iets nieuws op.

Fouten

Fouten gebruiken application/problem+json (RFC 9457). type linkt naar de uitleg hieronder, detail zegt wat er in dit geval misging. De teksten in de antwoorden zijn Engels.

{
    "type": "https://ladon.hackindex.io/docs/api#error-plan-limit",
    "title": "Plan limit reached",
    "status": 402,
    "detail": "Your plan allows 25 active watches. Pause or remove one, or upgrade the plan, to add more.",
    "instance": "/api/v1/watches",
    "limit": "watches",
    "upgrade_url": "https://account.hackindex.io/settings/teams/acme"
}
400

Ongeldige JSON

#invalid-json

De body is geen geldige JSON.

400

Ongeldige Idempotency-Key

#invalid-idempotency-key

De sleutel is langer dan 255 tekens.

401

Niet ingelogd

#unauthenticated

Geen token, een token dat niet bestaat, of een token dat is ingetrokken of verlopen. Ook als de eigenaar van het token niet meer in het team zit.

402

Limiet van het abonnement bereikt

#plan-limit

Het team gebruikt alle watches, projecten of kanalen die het abonnement toestaat. limit zegt welke, upgrade_url waar je upgradet.

402

Niet in je abonnement

#plan-feature

Het abonnement heeft dit niet, bijvoorbeeld de API bij het gratis abonnement of de events-API vóór Business. feature zegt welke.

403

Scope ontbreekt

#missing-scope

Het token heeft niet de scope die dit verzoek nodig heeft. Maak een token met die scope.

403

Rol ontbreekt

#missing-role

Kanalen en het bezorglog zijn voor owners en admins van het team.

403

Tweestapsverificatie vereist

#two-factor-required

Het team verplicht tweestapsverificatie. Zet die aan in je HackIndex-account.

403

Niet toegestaan

#forbidden

Het verzoek is niet toegestaan.

404

Niet gevonden

#not-found

Het bestaat niet, of het hoort bij een ander team.

405

Methode niet toegestaan

#method-not-allowed

Het pad bestaat, maar niet met deze methode.

409

Conflict

#conflict

Het verzoek botst met de huidige stand, bijvoorbeeld een watch die al bestaat of een bericht opnieuw sturen dat al bezorgd is.

422

Ongeldige velden

#validation

Een of meer velden kloppen niet. errors geeft de meldingen per veld.

422

Idempotency-Key hergebruikt

#idempotency-key-reused

De sleutel is in de laatste 24 uur gebruikt voor een ander verzoek. Gebruik voor elk nieuw verzoek een nieuwe sleutel.

429

Te veel verzoeken

#rate-limited

Wacht het aantal seconden uit Retry-After en probeer het opnieuw.

500

Serverfout

#server-error

Er ging iets mis aan onze kant. Probeer het later opnieuw. Een POST met een Idempotency-Key kun je veilig herhalen.

Versies

De versie staat in het pad: v1. Nieuwe velden en endpoints kunnen altijd bijkomen, dus negeer velden die je niet kent. Wijzigingen die een koppeling kunnen breken, komen met een nieuwe versie en worden aangekondigd in de changelog. Webhook-payloads hebben hun eigen api_version, zie Events en payloads.

Gegevens en licenties

Kwetsbaarheden hebben source, met een link naar het record en de copyrightvermeldingen van de gegevens. Houd die bij elke kopie die je maakt, bijvoorbeeld in een ticket of rapport. Alle licenties staan op de licentiepagina.