goanon

README

go-anon

Pipeline de reconnaissance d'entités nommées (NER) et d'anonymisation pour le français, l'anglais et l'espagnol.

Le cœur du pipeline NER (modèle CRF, features, tokenisation, anonymisation) est écrit en Go pur, sans dépendance externe. Le traitement des documents bureautiques (DOCX, PDF) et la détection automatique de langue s'appuient sur quelques bibliothèques tierces.

Fonctionnalités

• Détection d'entités nommées (personnes, lieux, organisations) via un modèle CRF linéaire ;
• Détection par expression régulière d'identifiants structurés (e-mail, IPv4/IPv6, IBAN, SIRET, SIREN, téléphone) et de secrets (JWT, clés OpenAI/AWS/GitHub/Slack/Stripe, Bearer) ;
• Anonymisation configurable : remplacement par tag, caviardage, empreinte HMAC ou pseudonymes cohérents ;
• Traitement de documents bureautiques : DOCX, ODT, CSV/TSV, PDF, avec sanitisation des surfaces cachées (métadonnées, commentaires, révisions) ;
• Détection automatique de la langue (fr/en/es) et téléchargement automatique des modèles pré-entraînés depuis GitHub Releases ;
• Vérification de la sortie et mode fail-closed : aucune sortie produite si une entité ou un identifiant structuré y reste détectable ;
• Mapping de ré-identification chiffré (AES-256-GCM), avec rétention et effacement cryptographique ;
• Serveur HTTP durci : isolation inter-requêtes sans état, plafonds de corps et de concurrence, logs limités aux métadonnées ;
• Presets précision/rappel (balanced, high-recall) et métriques orientées conformité (rappel par type/langue, F2) ;
• Vérification de signature Ed25519 (minisign) du manifeste des modèles.

Utilisation

go get github.com/bornholm/go-anon

import goanon "github.com/bornholm/go-anon"

// Charger un modèle
f, _ := os.Open("model_fr.crf.gz")
m, _ := goanon.LoadModel(f)

// Reconnaître des entités
r, _ := goanon.NewRecognizer(m, goanon.WithLanguage("fr"))
entities, _ := r.Recognize("Jean Dupont habite à Paris.")
// → [{Text:"Jean Dupont", Type:"PER"}, {Text:"Paris", Type:"LOC"}]

// Anonymiser
anon := goanon.NewAnonymizer(r, goanon.Config{Strategy: goanon.TagReplace})
result, _ := anon.Anonymize("Jean Dupont habite à Paris.")
// result.Text → "⟦PERSON_1_a3f9c2⟧ habite à ⟦LOCATION_1_a3f9c2⟧."

// Restaurer le texte original
restored, _ := goanon.Deanonymize(result.Text, result.Mapping)

// Mode fail-closed : aucune sortie si une entité subsiste dans le texte anonymisé
result, err := anon.Anonymize(texte, goanon.WithStrictVerification())

// Détection des identifiants structurés (e-mail, IP, IBAN…) et des secrets
r, _ = goanon.NewRecognizer(m,
    goanon.WithLanguage("fr"),
    goanon.WithBuiltinRegexPatterns(),
    goanon.WithBuiltinSecretPatterns(), // JWT, sk-, AKIA, ghp_, xox*, sk_live_, Bearer…
)

// Détecter automatiquement la langue avant de choisir le modèle
det := goanon.NewWhatlangDetector(goanon.SupportedLanguages()...)
res, _ := det.Detect("Jean Dupont habite à Paris.")
// res.Lang → "fr" (si res.Reliable)

En ligne de commande, la langue est détectée automatiquement par défaut :

# La langue est détectée à partir du contenu du document (-lang auto par défaut)
anon-doc -model auto -input rapport.docx -output rapport_anon.docx
# ou forcée explicitement
anon-doc -model auto -lang fr -input rapport.docx -output rapport_anon.docx

Garanties de traitement

La bibliothèque réalise une pseudonymisation au sens de l'art. 4(5) du RGPD, pas une anonymisation : le mapping de ré-identification est lui-même une donnée personnelle, et l'actif le plus sensible du système. Le protéger et le détruire après usage est ce qui rend la sortie anonyme de facto. Par défaut, la sortie est réversible (pseudonymisée), pas anonyme.

Ce que l'outil garantit

• en mode strict : aucune forme de surface d'entité détectée ni identifiant structuré ne reste en clair, sinon échec sans sortie ;
• les secrets (clés, JWT) n'entrent jamais dans le mapping ;
• la stratégie hash n'est pas cassable par dictionnaire sans la clé (HMAC) ;
• round-trip déterministe et total ;
• purge des métadonnées/commentaires/révisions des documents ;
• isolation inter-requêtes du serveur, logs sans contenu.

Ce que l'outil ne garantit pas

• l'exhaustivité de la détection (un nom manqué par le modèle part en clair, préférer alors le preset haut rappel) ;
• la couverture des quasi-identifiants combinables, paraphrases, inférences contextuelles, stylométrie ;
• la zéroïsation mémoire (limite du langage) ni l'écrasement disque physique (l'effacement réel est cryptographique).

Modèle de menace complet, garanties mesurées et checklist de déploiement : docs/rgpd.md.

Documentation

Document	Contenu
docs/anonymisation.md	Secrets, placeholders, stratégies de remplacement (dont hash), vérification fail-closed, presets précision/rappel
docs/documents.md	Formats bureautiques pris en charge et sanitisation des surfaces cachées
docs/deploiement.md	Stockage chiffré du mapping, durcissement du serveur HTTP, authenticité des modèles
docs/rgpd.md	Cadrage juridique, modèle de menace, garanties mesurées, checklist de déploiement
docs/tutoriel-modele.md	Entraîner un modèle NER depuis les données WikiNER

Licence

GPL-3.0

Documentation

Overview

Package goanon fournit une API de haut niveau pour la reconnaissance d'entités nommées (NER) et l'anonymisation de texte en français, anglais et espagnol.

Usage minimal :

f, _ := os.Open("model.crf.gz")
m, err := goanon.LoadModel(f)
r, err := goanon.NewRecognizer(m, goanon.WithLanguage("fr"))
entities, err := r.Recognize("Jean Dupont habite à Paris.")

Le Recognizer applique par défaut la configuration d'inférence validée sur WikiNER : ponctuation conservée dans les séquences CRF et découpage aux seules fins de phrase (cf. WithPunctuationTokens, WithSentenceBoundaries). NewRecognizer propage automatiquement le schéma de features et la fenêtre de contexte enregistrés dans le modèle ; Recognizer.Warnings() signale tout écart entre la configuration du modèle et celle de l'inférence (gazetteers ou Brown clusters manquants, langue différente).

Anonymisation :

anon := goanon.NewAnonymizer(r, goanon.Config{Strategy: goanon.TagReplace})
result, err := anon.Anonymize("Jean Dupont habite à Paris.")
// result.Text == "[PERSON_1] habite à [LOCATION_1]."

Index

• Constants
• Variables
• type AnonymizeOption
• type AnonymizePass
• type BrownClusters
• type Config
• type Entity
• type EntityFilter
• type EntityType
• type Gazetteer
• type HashKey
• type LanguageDetector
• type LanguageResult
• type Leak
• type LeakKind
• type Model
• type Preset
• type Recognizer
• type RecognizerOption
• type RegexPattern
• type ReplacerFunc
• type Result
• type Session
• type SessionState
• type Strategy
• type VerificationError
• type VerificationReport

Constants

const (
	TypePER  = ner.TypePER
	TypeLOC  = ner.TypeLOC
	TypeORG  = ner.TypeORG
	TypeMISC = ner.TypeMISC

	TypeEMAIL = ner.TypeEMAIL
	TypeIPV4  = ner.TypeIPV4
	TypeIPV6  = ner.TypeIPV6
	TypeIBAN  = ner.TypeIBAN
	TypeSIRET = ner.TypeSIRET
	TypeSIREN = ner.TypeSIREN
	TypePHONE = ner.TypePHONE

	TypeAPIKey = ner.TypeAPIKey
	TypeJWT    = ner.TypeJWT
	TypeSecret = ner.TypeSecret
)

const (
	LeakKnownEntity               = anonymizer.LeakKnownEntity
	LeakRegexHit                  = anonymizer.LeakRegexHit
	LeakInvalidUTF8               = anonymizer.LeakInvalidUTF8
	LeakResidualPlaceholderSource = anonymizer.LeakResidualPlaceholderSource
)

const (
	TagReplace = anonymizer.TagReplace
	Redact     = anonymizer.Redact
	Hash       = anonymizer.Hash
	Consistent = anonymizer.Consistent
)

const (
	PresetBalanced   = ner.PresetBalanced
	PresetHighRecall = ner.PresetHighRecall
)

const HashKeyEnvVar = anonymizer.HashKeyEnvVar

HashKeyEnvVar nomme la variable d'environnement portant la clé HMAC.

Variables

var (
	ErrHashKeyRequired      = anonymizer.ErrHashKeyRequired
	ErrHashKeyTooShort      = anonymizer.ErrHashKeyTooShort
	ErrHashKeyNotSet        = anonymizer.ErrHashKeyNotSet
	ErrHashKeyFormat        = anonymizer.ErrHashKeyFormat
	ErrPlaceholderCollision = anonymizer.ErrPlaceholderCollision
	ErrIncompleteMapping    = anonymizer.ErrIncompleteMapping
	ErrVerificationFailed   = anonymizer.ErrVerificationFailed
	ErrSessionClosed        = anonymizer.ErrSessionClosed
	ErrSessionFull          = anonymizer.ErrSessionFull
)

Erreurs sentinelles de l'anonymiseur.

var Balanced = ner.Balanced

Balanced retourne les options du preset par défaut (compromis F1).

var BlocklistFilter = ner.BlocklistFilter

var BuiltinRegexPatterns = ner.BuiltinRegexPatterns

var ConsistencyPass = anonymizer.ConsistencyPass

var Deanonymize = anonymizer.Deanonymize

Deanonymize restaure le texte original depuis un mapping placeholder → original.

var DefaultSentenceBoundaries = ner.DefaultSentenceBoundaries

var DefaultVerifyPatterns = anonymizer.DefaultVerifyPatterns

DefaultVerifyPatterns liste les expressions régulières re-passées sur la sortie par défaut lors de la vérification.

var FirstNameDetectionFilter = ner.FirstNameDetectionFilter

var FirstNameReclassifyFilter = ner.FirstNameReclassifyFilter

var HashKeyFromEnv = anonymizer.HashKeyFromEnv

HashKeyFromEnv charge la clé HMAC depuis GOANON_HASH_KEY.

var HighRecall = ner.HighRecall

HighRecall retourne les options du preset « haut rappel » recommandé pour la conformité RGPD (à combiner avec WithStrictVerification).

var IsSecretType = ner.IsSecretType

IsSecretType identifie les types dont la valeur n'est jamais conservée dans un mapping ni ré-identifiable (clés d'API, JWT, mots de passe).

var LoadBrownClusters = features.LoadBrownClusters

var LoadGazetteer = features.LoadGazetteer

var LoadModel = ner.LoadModel

LoadModel charge un modèle CRF sérialisé depuis r (format gob+gzip).

var MaxTokensFilter = ner.MaxTokensFilter

var MergePass = ner.MergePass

var MinConfidenceFilter = ner.MinConfidenceFilter

var NameCompletionPass = ner.NameCompletionPass

var NewAnonymizer = anonymizer.New

NewAnonymizer crée un Anonymizer qui s'appuie sur le Recognizer donné.

var NewRecognizer = ner.New

NewRecognizer construit un Recognizer NER avec le modèle m et les options fournies. Voir WithLanguage, WithGazetteers, WithBrownClusters, WithPostFilters.

var NewSession = anonymizer.NewSession

var NewSessionFromState = anonymizer.NewSessionFromState

NewSessionFromState reconstruit une Session depuis son état sérialisé.

var NewWhatlangDetector = langdetect.NewWhatlangDetector

NewWhatlangDetector construit un détecteur de langue basé sur whatlanggo, restreint aux codes ISO 639-1 fournis.

var ParseHashKey = anonymizer.ParseHashKey

ParseHashKey décode une clé HMAC hexadécimale ou base64 (≥ 32 octets).

var PresetOptions = ner.PresetOptions

PresetOptions retourne les options associées à un preset nommé.

var RegexEntityFilter = ner.RegexEntityFilter

var SecretPatterns = ner.SecretPatterns

var SupportedLanguages = ner.SupportedLanguages

SupportedLanguages retourne les codes ISO 639-1 gérés par le pipeline (fr/en/es).

var SurnameCompletionPass = anonymizer.SurnameCompletionPass

var Verify = anonymizer.Verify

Verify recontrôle une sortie anonymisée : formes de surface résiduelles, identifiants structurés re-détectables, corruption d'encodage.

var WithBrownClusters = ner.WithBrownClusters

var WithBuiltinRegexPatterns = ner.WithBuiltinRegexPatterns

var WithBuiltinSecretPatterns = ner.WithBuiltinSecretPatterns

var WithConfidenceScores = ner.WithConfidenceScores

var WithEscapeCollisions = anonymizer.WithEscapeCollisions

var WithExposeSecrets = anonymizer.WithExposeSecrets

var WithFirstNameDetectionPass = ner.WithFirstNameDetectionPass

var WithFirstNameReclassify = ner.WithFirstNameReclassify

var WithGazetteers = ner.WithGazetteers

var WithHashKey = anonymizer.WithHashKey

var WithHashScope = anonymizer.WithHashScope

var WithInsecureHash = anonymizer.WithInsecureHash

var WithLanguage = ner.WithLanguage

var WithLegacyPlaceholders = anonymizer.WithLegacyPlaceholders

var WithMergePass = ner.WithMergePass

var WithNameCompletionPass = ner.WithNameCompletionPass

var WithPostFilters = ner.WithPostFilters

var WithPunctuationTokens = ner.WithPunctuationTokens

var WithRegexPatterns = ner.WithRegexPatterns

var WithSentenceBoundaries = ner.WithSentenceBoundaries

var WithSession = anonymizer.WithSession

var WithStrictVerification = anonymizer.WithStrictVerification

var WithVerification = anonymizer.WithVerification

var WithVerifyPatterns = anonymizer.WithVerifyPatterns

Types

type AnonymizeOption

type AnonymizeOption = anonymizer.AnonymizeOption

type AnonymizePass

type AnonymizePass = anonymizer.AnonymizePass

type BrownClusters

type BrownClusters = features.BrownClusters

type Config

type Config = anonymizer.Config

type Entity

type Entity = ner.Entity

type EntityFilter

type EntityFilter = ner.EntityFilter

type EntityType

type EntityType = ner.EntityType

type Gazetteer

type Gazetteer = features.Gazetteer

type HashKey

type HashKey = anonymizer.HashKey

type LanguageDetector

type LanguageDetector = langdetect.Detector

type LanguageResult

type LanguageResult = langdetect.Result

type Leak

type Leak = anonymizer.Leak

type LeakKind

type LeakKind = anonymizer.LeakKind

type Model

type Model = ner.Model

type Preset

type Preset = ner.Preset

Preset nomme un compromis précision/rappel (cf. Balanced, HighRecall).

type Recognizer

type Recognizer = anonymizer.Recognizer

type RecognizerOption

type RecognizerOption = ner.RecognizerOption

type RegexPattern

type RegexPattern = ner.RegexPattern

RegexPattern associe une expression régulière à un type d'entité.

type ReplacerFunc

type ReplacerFunc = anonymizer.ReplacerFunc

type Result

type Result = anonymizer.Result

type Session

type Session = anonymizer.Session

type SessionState

type SessionState = anonymizer.SessionState

type Strategy

type Strategy = anonymizer.Strategy

type VerificationError

type VerificationError = anonymizer.VerificationError

type VerificationReport

type VerificationReport = anonymizer.VerificationReport