A Kubernetes operator for fraud detection and risk evaluation, built with Kubebuilder. It provides a pipeline-based approach to evaluating user fraud risk using pluggable providers (currently MaxMind minFraud).
The service is composed of three Custom Resource Definitions (CRDs) that work together:
FraudProvider FraudPolicy FraudEvaluation
┌──────────────┐ ┌───────────────────┐ ┌──────────────────────┐
│ Configures a │◄─────│ Defines pipeline │◄────│ Evaluates a user │
│ provider │ │ stages, thresholds│ │ against the policy │
│ (e.g.MaxMind)│ │ & enforcement mode│ │ and records results │
└──────────────┘ └───────────────────┘ └──────────────────────┘
Configures a fraud detection provider backend.
| Field | Description |
|---|---|
spec.type |
Provider type (maxmind) |
spec.failurePolicy |
Behavior on provider failure — FailOpen (score 0) or FailClosed (high risk) |
spec.config.endpoint |
Optional API endpoint override |
spec.config.credentialsRef |
Reference to a Secret containing API credentials |
Defines the evaluation pipeline — stages, score thresholds, enforcement mode, and history retention. Typically a singleton per cluster.
| Field | Description |
|---|---|
spec.stages[] |
Ordered evaluation pipeline stages |
spec.stages[].providers[] |
Provider references to invoke in this stage |
spec.stages[].thresholds[] |
Score thresholds that trigger actions (REVIEW, DEACTIVATE) |
spec.stages[].shortCircuit.skipWhenBelow |
Skip subsequent non-required stages if max score is below this value |
spec.enforcement.mode |
OBSERVE (log only) or AUTO (enforce actions) |
spec.historyRetention.maxEntries |
Max evaluation history entries to retain (default: 50) |
Represents the fraud evaluation state for a specific user. Created to trigger an evaluation, then updated with results as the pipeline runs.
| Field | Description |
|---|---|
spec.userRef.name |
User being evaluated |
spec.policyRef.name |
Policy to evaluate against |
status.phase |
Pending → Running → Completed or Error |
status.compositeScore |
Overall risk score (0–100, highest across all providers) |
status.decision |
NONE, REVIEW, or DEACTIVATE |
status.enforcementAction |
Action taken: NONE, OBSERVED, REVIEW_FLAGGED, DEACTIVATED |
status.stageResults[] |
Per-stage and per-provider detailed results |
status.history[] |
Previous evaluation results for audit |
- FraudProviderReconciler — Validates provider config, loads credentials, and registers providers in a shared in-memory registry.
- FraudPolicyReconciler — Validates that all referenced providers exist and are available, sets policy conditions accordingly.
- FraudEvaluationReconciler — Executes the evaluation pipeline: invokes providers, computes composite scores, applies thresholds, enforces decisions, and maintains evaluation history.
- Go 1.24+
- Docker 17.03+
- kubectl v1.11.3+
- Access to a Kubernetes cluster
# Install CRDs into the cluster
make install
# Run the controller locally
make run
# Apply sample resources
kubectl apply -k config/samples/# Build and push the controller image
make docker-build docker-push IMG=<registry>/fraud:tag
# Deploy to the cluster
make deploy IMG=<registry>/fraud:tag# Run unit tests
make test
# Run e2e tests (requires a running cluster)
make test-e2ekubectl delete -k config/samples/ # Remove sample CRs
make uninstall # Remove CRDs
make undeploy # Remove the controller├── api/v1alpha1/ # CRD type definitions
├── cmd/ # Controller entrypoint
├── config/
│ ├── crd/ # Generated CRD manifests
│ ├── default/ # Default Kustomize deployment
│ ├── iam/ # IAM protected resources & roles
│ ├── manager/ # Controller manager deployment
│ ├── rbac/ # RBAC roles for CRD access
│ └── samples/ # Example CR manifests
├── internal/
│ ├── controller/ # Reconcilers for each CRD
│ ├── datasource/ # User data resolution
│ └── provider/ # Provider interface & implementations
│ └── maxmind/ # MaxMind minFraud provider
└── test/ # E2E tests
This project is licensed under the GNU Affero General Public License v3.0.