Arnakoff API

API publique anti-arnaque : pour un site, un e-mail, un numéro de téléphone, un IBAN ou un SIREN, elle renvoie des signaux sourcés expliqués en français.

Statut

En construction : aucune version n'est publiée et l'API n'est pas encore en service. Les commandes de cmd/ ne font encore rien. Suis l'avancement dans la feuille de route.

Related MCP server: scamshield

Ce que fait l'API

Tu lui donnes une entrée ; elle la confronte à des sources publiques (listes noires de l'AMF et de l'ACPR, répertoire SIRENE, BODACC, âge du domaine, numérotation de l'ARCEP…) et renvoie une liste de signaux. Chaque signal porte :

• code : identifiant stable du signal ;

• level : niveau du signal ;

• message : une phrase factuelle en français, par exemple « Figure sur la liste noire de l'AMF depuis le 08/10/2026 » ;

• source et source_url : l'éditeur de la donnée et où la vérifier ;

• observed_at : la date à laquelle la donnée a été relevée.

Les signaux prévus sont dans docs/signals.md, les sources et leurs licences dans docs/sources.md. L'API est aussi exposée comme serveur MCP : à distance sur POST /mcp, avec la même clé et le même quota que /v1/check, ou en local avec cmd/mcp (stdio). Il figure dans le registre MCP officiel sous le nom com.arnakoff/api.

Principes

• Jamais « sûr ». Sans signal, la réponse est « Aucun signal connu dans nos sources » : l'absence d'une liste noire ne prouve rien.

• Des faits, pas des accusations. Chaque signal cite sa source ; aucun message ne qualifie une entité nommée d'arnaque.

• Des licences d'abord. Une source n'est utilisée que si sa licence autorise la réutilisation commerciale.

• Les données personnelles protégées. Les e-mails, numéros et IBAN ne sont jamais journalisés en clair ni transmis à un tiers.

• Aucune URL fournie par l'utilisateur n'est appelée. Les registres sont interrogés par identifiant, à travers une liste d'hôtes autorisés.

• Une synchronisation prudente. Un instantané de source invalide, ou qui perd plus de 20 % de ses entrées, est rejeté ; le précédent reste en service.

Démarrer

Il te faut Go 1.27 : la version exacte (toolchain go1.27.3) est dans go.mod et se télécharge d'elle-même. Installe aussi golangci-lint à la version indiquée dans docs/standards.md.

go build ./...
go vet ./...
golangci-lint run
go test -race -shuffle=on ./...
go tool govulncheck ./... tool

La CI lance les mêmes commandes sur chaque pull request. Les tests n'utilisent jamais le réseau.

Avec Docker, l'image (Dockerfile) contient les commandes api, sync et admin sur une base distroless sans shell, exécutées par un utilisateur non root. compose.yaml lance l'API et la synchronisation, qui partagent le volume des instantanés :

cp .env.example .env   # renseigner ARNAKOFF_LOG_KEY, ARNAKOFF_DATABASE_URL et ARNAKOFF_API_KEY_SECRET
docker compose up --build

Chaque version publiée (tag vX.Y.Z) produit l'image ghcr.io/arnakoff/api pour linux/amd64 et linux/arm64, taguée X.Y.Z, X.Y et latest, avec son SBOM et son attestation de provenance. Elle est signée sans clé par cosign depuis le workflow image.yml ; pour vérifier la signature d'une version (ici 0.48.0) :

cosign verify ghcr.io/arnakoff/api:0.48.0 \
  --certificate-identity https://github.com/arnakoff/api/.github/workflows/image.yml@refs/tags/v0.48.0 \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

Le SBOM et la provenance se lisent avec docker buildx imagetools inspect ghcr.io/arnakoff/api:0.48.0 --format '{{ json .SBOM.SPDX }}' (ou '{{ json .Provenance.SLSA }}').

Organisation

Architecture propre (ADR 0002) : les dépendances vont vers l'intérieur uniquement.

Documentation

• Décisions d'architecture : 0001 — Socle technique, 0002 — Architecture propre, 0003 — Licences, 0004 — Stockage des clés et des quotas, 0005 — Hébergement de production, 0006 — Durées de conservation.

• Standards et versions, sources, signaux.

• Le site et la documentation publique de l'API sont dans arnakoff/web.

Contribuer

Lis CONTRIBUTING.md. Pour une faille de sécurité, suis la politique de sécurité, jamais une issue publique. Pour de l'aide, vois SUPPORT.md.

Licence

Le code est sous GNU AGPL-3.0-only (ADR 0003). Les données gardent la licence de leur source, indiquée dans docs/sources.md.