Spaces:

yusufcalisir
/

Collaborative-Fraud-Intelligence-Simulator

Runtime error

App Files Files Community

Collaborative-Fraud-Intelligence-Simulator / docs /cfi_cli_user_guide.md

yusufcalisir

deploy: Hugging Face space upload

73ba4f5 about 22 hours ago

preview code

Raw History Blame Contribute Delete

15.3 kB

Official Command-Line Interface (`cfi-cli`) User Guide (2026 Edition)

1. Executive Overview & Architecture

The Collaborative Fraud Intelligence Platform (CF-Intelligence) provides a unified, dual-purpose Command-Line Interface (CLI) ecosystem engineered for enterprise DevSecOps, Site Reliability Engineers (SREs), and bank IT integration teams:

┌────────────────────────────────────────────────────────────────────────────────────────┐
│                        CFI COMMAND-LINE INTERFACE ECOSYSTEM                            │
├───────────────────────────────────────────┬────────────────────────────────────────────┤
│ 1. PRODUCTION OPERATOR CLI (`cfi-cli`)    │ 2. BANK ONBOARDING SANDBOX (`cfi_cli.py`)  │
│  - Installed via `pip install -e backend` │  - Standalone script: `scripts/cfi_cli.py` │
│  - Targets Coordinator Admin REST APIs    │  - Offline pre-flight & hardware discovery │
│  - Manages Live mTLS, Status & Deployments│  - Scaffolds local configs & 4096-bit CSR  │
│  - Exports SHA-256 Signed Telemetry       │  - Tests gRPC ports & runs TPS benchmarks  │
└───────────────────────────────────────────┴────────────────────────────────────────────┘

Production Operator CLI (cfi-cli): Installed globally as cfi-cli via backend/pyproject.toml (entrypoint backend/app/presentation/cli/cfi_cli.py). Interacts with coordinator REST endpoints for consortium enrollment, live status queries, zero-downtime certificate rotation, signed diagnostic bundles, and rolling deployments.
Bank Onboarding & Self-Service Sandbox CLI (scripts/cfi_cli.py): A standalone self-service tool located in scripts/cfi_cli.py. Enables bank IT infrastructure engineers to perform Day-0 integration, scaffold local directories, generate X.509 Certificate Signing Requests (CSR), verify outbound gRPC network reachability, and benchmark local hardware inference throughput.

2. Installation, Environment & File Hierarchy

2.1. Installation

Operator CLI (Global Console Script):

pip install -e backend
cfi-cli --version
# Expected: cfi-cli v2.0.0

Bank Onboarding Sandbox (Zero-Install / Direct Script Execution):

python scripts/cfi_cli.py --help

2.2. Environment Configuration

Variable	Default Value	Description
`CFI_HOME`	`~/.cfi`	Base filesystem root for keys, certificates, connector YAMLs, and active bank pointer
`CFI_LOG_LEVEL`	`INFO`	Logging verbosity (`DEBUG`, `INFO`, `WARNING`, `ERROR`)

2.3. On-Disk Directory Structure (`CFI_HOME`)

~/.cfi/
├── certs/
│   ├── {bank_id}.crt       # Issued mTLS node certificate (PEM format)
│   └── {bank_id}.key       # RSA / ECDSA private key (0600 permissions, PEM format)
├── config/
│   ├── {bank_id}.yaml      # Production connector configuration (YAML format)
│   └── active_bank         # JSON pointer storing active {"bank_id", "coordinator_url"}
└── data/
    └── vault/              # Local encrypted cache for offline inference tokens

3. Production Operator CLI Reference (`cfi-cli`)

The production operator CLI is backed by backend/app/presentation/cli/cfi_cli.py.

3.1. `cfi-cli join`

Enrolls a new banking institution with the coordinator consortium and provisions the mTLS keypair and connector configuration.

cfi-cli join \
  --bank-id bank_alpha \
  --coordinator-url https://coordinator.cf-intelligence.io \
  --legal-name "Alpha National Bank" \
  --jurisdiction TR \
  --contact-email security@alphabank.com \
  --data-residency-region eu-west-1

Execution Output:

✅ Bank 'bank_alpha' registered successfully.
   Cert   → ~/.cfi/certs/bank_alpha.crt
   Key    → ~/.cfi/certs/bank_alpha.key
   Config → ~/.cfi/config/bank_alpha.yaml
   Run: cfi-cli start-daemon --bank-id bank_alpha

Parameter Reference:

Flag	Type	Required	Description
`--bank-id`	`string`	✅	Unique alphanumeric bank node identifier (e.g., `bank_alpha`, `jpm_global`)
`--coordinator-url`	`string`	✅	Base URL of the consortium coordinator API
`--legal-name`	`string`	✅	Full legal entity name for compliance registry
`--jurisdiction`	`string`	✅	ISO 3166-1 alpha-2 country code (`TR`, `US`, `DE`, `GB`)
`--contact-email`	`string`	✅	Official corporate security contact email
`--data-residency-region`	`string`	✅	Target sovereign cloud boundary (e.g., `eu-west-1`, `us-east-1`)

3.2. `cfi-cli status`

Inspects real-time bank node status, mTLS certificate fingerprints, and activation timestamps from the coordinator.

cfi-cli status

Execution Output:

┌─ Bank Status ────────────────────────────────────────
│  bank_id        : bank_alpha
│  legal_name     : Alpha National Bank
│  jurisdiction   : TR
│  status         : ACTIVE
│  cert_fingerprint: abc123def456789012...
│  activated_at   : 2026-07-24T18:05:00
└──────────────────────────────────────────────────────

Offline Fallback Note: If no active_bank configuration exists, status prints a safe offline development stub reminding the operator to execute cfi-cli join first.

3.3. `cfi-cli rotate-certs`

Performs automated zero-downtime certificate rotation for an active bank node, atomically replacing the on-disk .crt and .key files.

cfi-cli rotate-certs --bank-id bank_alpha

Execution Output:

✅ Certificate rotated for 'bank_alpha'.
   Fingerprint: d4e5f6a7b8c9101112...
   Cert saved → ~/.cfi/certs/bank_alpha.crt

3.4. `cfi-cli export-diagnostics`

Collects host system telemetry, OS architecture, Python runtime version, certificate modification timestamps, and SLA compliance counters into a SHA-256 cryptographically signed JSON bundle.

cfi-cli export-diagnostics --output /tmp/cfi_diag.json

Execution Output:

✅ Diagnostics bundle saved to /tmp/cfi_diag.json
   SHA-256: 3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e

Diagnostic JSON Bundle Structure:

{
  "cli_version": "v2.0.0",
  "hostname": "node-alpha-prod-01",
  "os": "Linux-6.1.0-28-generic-x86_64",
  "python_version": "3.12.10",
  "active_bank_id": "bank_alpha",
  "cert_file_mtime": 1787593200.0,
  "logs": [
    "No critical errors encountered.",
    "SLA compliance 99.99%."
  ],
  "metrics": {
    "p95_latency_ms": 9.84,
    "error_budget_remaining_pct": 100.0
  },
  "sha256_signature": "3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e"
}

3.5. `cfi-cli health`

Queries internal microservice status to verify local readiness and liveness endpoints.

cfi-cli health

Execution Output:

{
  "status": "UP",
  "components": {
    "inference_engine": "HEALTHY",
    "federated_coordinator": "HEALTHY",
    "privacy_guard": "HEALTHY",
    "dr_manager": "HEALTHY"
  }
}

3.6. `cfi-cli deploy`

Triggers rolling node deployment and drains in-flight TCP connections prior to binary upgrades.

cfi-cli deploy --target-version v2.2.0

Execution Output:

{
  "target_version": "v2.2.0",
  "stage": "DRAINING_CONNECTIONS",
  "message": "Rolling deployment to v2.2.0 initiated."
}

4. Bank Onboarding & Integration Sandbox CLI (`scripts/cfi_cli.py`)

The self-service onboarding tool in scripts/cfi_cli.py provides pre-flight checks for bank IT infrastructure teams.

4.1. `python scripts/cfi_cli.py init`

Scaffolds local directories and generates a production bank_config.yaml template:

python scripts/cfi_cli.py init \
  --bank-id bank_alpha \
  --coordinator coordinator.cf-intelligence.io:50051 \
  --output-dir ./bank_alpha_node

Generated Scaffold:

./bank_alpha_node/
├── bank_config.yaml      # Pre-filled connection & mTLS settings
├── certs/                # Mount directory for node certificates
├── data/vault/           # Encrypted local key-value store
└── logs/                 # Rolling audit logs

4.2. `python scripts/cfi_cli.py cert generate-csr`

Generates a cryptographic 4096-bit RSA private key and an X.509 Certificate Signing Request (CSR) compliant with the consortium PKI:

python scripts/cfi_cli.py cert generate-csr \
  --bank-id bank_alpha \
  --output-dir ./bank_alpha_node/certs \
  --country TR \
  --org "Alpha National Bank"

Generated Artifacts:

certs/bank_alpha.key: 4096-bit RSA Private Key (0600 permissions)
certs/bank_alpha.csr: X.509 Certificate Signing Request (CN=bank_alpha.client.cf-intelligence.io)

4.3. `python scripts/cfi_cli.py test-connection`

Probes outbound network connectivity and gRPC handshake latency to the coordinator node:

python scripts/cfi_cli.py test-connection \
  --host coordinator.cf-intelligence.io \
  --port 50051 \
  --timeout 5.0

Execution Output:

{
  "status": "ok",
  "command": "test-connection",
  "target": "coordinator.cf-intelligence.io:50051",
  "latency_ms": 3.42,
  "handshake_sla": "PASS",
  "note": "gRPC TCP port is open and responsive."
}

4.4. `python scripts/cfi_cli.py sandbox run`

Launches an offline synthetic transaction stress test to benchmark local CPU/GPU hardware throughput against the >100 TPS SLA:

python scripts/cfi_cli.py sandbox run --transactions 5000

Execution Output:

{
  "status": "ok",
  "command": "sandbox run",
  "transactions_generated": 5000,
  "fraud_transactions": 26,
  "fraud_rate_pct": 0.52,
  "generation_elapsed_sec": 0.024,
  "processing_elapsed_sec": 0.018,
  "total_elapsed_sec": 0.042,
  "throughput_tps": 119047.6,
  "throughput_sla": "PASS",
  "hardware": {
    "pytorch_available": true,
    "pytorch_version": "2.12.0+cpu",
    "cuda_available": false,
    "cuda_device": null,
    "mps_available": false,
    "recommended_device": "cpu"
  },
  "next_step": "Sandbox validation successful. Deploy cfi-bank-client container and run cfi-cli test-connection to verify live coordinator connectivity."
}

5. Institutional Operator Workflows (Day-0, Day-1, Day-2)

[ Day-0: Pre-Flight Sandbox ] ──► [ Day-1: Production Onboarding ] ──► [ Day-2: SRE Maintenance ]
  1. `cfi-cli init`                 1. `cfi-cli join`                    1. `cfi-cli status`
  2. `cfi-cli cert generate-csr`     2. Validate cert fingerprints       2. `cfi-cli rotate-certs`
  3. `cfi-cli test-connection`      3. Launch edge daemon container      3. `cfi-cli export-diagnostics`
  4. `cfi-cli sandbox run`          4. Quorum activation confirmation    4. `cfi-cli deploy`

Day-0: Pre-Flight IT Readiness

Generate initial scaffold: python scripts/cfi_cli.py init --bank-id bank_beta
Validate hardware throughput: python scripts/cfi_cli.py sandbox run --transactions 1000
Generate node CSR: python scripts/cfi_cli.py cert generate-csr --bank-id bank_beta
Confirm network firewall rules: python scripts/cfi_cli.py test-connection --host coordinator.prod --port 50051

Day-1: Production Consortium Enrollment

Register bank node: cfi-cli join --bank-id bank_beta --coordinator-url https://coordinator.prod ...
Verify node status: cfi-cli status
Deploy local connector container mount with ~/.cfi/certs/bank_beta.crt and bank_beta.key

Day-2: Continuous SRE Operations

Weekly certificate lifecycle check: cfi-cli status
Zero-downtime certificate rollover: cfi-cli rotate-certs --bank-id bank_beta
Audit telemetric bundle generation: cfi-cli export-diagnostics --output /var/log/cfi_audit.json
Blue-Green node upgrade: cfi-cli deploy --target-version v2.3.0

6. Troubleshooting & Error Recovery Playbook

Error Signature	Root Cause	Operator Remediation
`❌ Error: No active_bank config found`	CLI invoked before `join` command execution	Execute `cfi-cli join` with valid bank parameters or export `CFI_HOME`
`HTTP 409 from .../register: Bank already registered`	Bank ID already exists in the coordinator ledger	Check existing state with `cfi-cli status` or enroll with unique `--bank-id`
`Connection failed to ...: Connection refused`	Coordinator API endpoint unreachable or firewall blocked	Verify outbound egress on ports 443 (REST) and 50051 (gRPC)
`cryptography library not found`	Python environment missing cryptographic primitives	Run `pip install cryptography` or execute within virtual environment
`SLA breach: throughput_tps < 100`	CPU contention or insufficient memory during sandbox run	Provision minimum 4 vCPUs and 8GB RAM, or enable GPU acceleration

7. Automated Test Verification Matrix

All CLI subcommands, argument parsers, diagnostic SHA-256 signing routines, and network mocks are covered by automated unit and integration tests:

Test Suite	File Path	Verified Technical Capabilities	Status
CLI Core Unit Tests	`test_cfi_cli.py`	Subcommand execution (`status`, `health`, `deploy`, `export-diagnostics`), CLI entrypoint argument parsing	`2/2 PASSED`
CLI Command Mock Tests	`test_cfi_cli_commands.py`	`join` cert disk persistence, `status` table render, `rotate-certs` atomic overwrite, SHA-256 signature verification	`4/4 PASSED`
gRPC mTLS Network Integration	`test_grpc_mtls.py`	Valid cert connection, CN pattern validation, expired cert rejection, unauthorized bank rejection	`13/13 PASSED`
Total Test Coverage	3 Test Suites	Comprehensive Packaging, Execution & Cryptographic Verification	19/19 PASSED

8. Related Architectural & Operational References

Bank Onboarding & Integration Architecture: docs/bank_onboarding_guide.md
Production Infrastructure & Vault HSM: docs/production_infrastructure.md
Developer & OpenAPI Integration Portal: docs/developer_and_api_portal.md
Production Engineering Decisions & ADRs: docs/engineering_decisions.md

Official Command-Line Interface (cfi-cli) User Guide (2026 Edition)

1. Executive Overview & Architecture

2. Installation, Environment & File Hierarchy

2.1. Installation

2.2. Environment Configuration

2.3. On-Disk Directory Structure (CFI_HOME)

3. Production Operator CLI Reference (cfi-cli)

3.1. cfi-cli join

3.2. cfi-cli status

3.3. cfi-cli rotate-certs

3.4. cfi-cli export-diagnostics

3.5. cfi-cli health

3.6. cfi-cli deploy

4. Bank Onboarding & Integration Sandbox CLI (scripts/cfi_cli.py)

4.1. python scripts/cfi_cli.py init

4.2. python scripts/cfi_cli.py cert generate-csr

4.3. python scripts/cfi_cli.py test-connection

4.4. python scripts/cfi_cli.py sandbox run

5. Institutional Operator Workflows (Day-0, Day-1, Day-2)

Day-0: Pre-Flight IT Readiness

Day-1: Production Consortium Enrollment

Day-2: Continuous SRE Operations

6. Troubleshooting & Error Recovery Playbook

7. Automated Test Verification Matrix

8. Related Architectural & Operational References

Official Command-Line Interface (`cfi-cli`) User Guide (2026 Edition)

2.3. On-Disk Directory Structure (`CFI_HOME`)

3. Production Operator CLI Reference (`cfi-cli`)

3.1. `cfi-cli join`

3.2. `cfi-cli status`

3.3. `cfi-cli rotate-certs`

3.4. `cfi-cli export-diagnostics`

3.5. `cfi-cli health`

3.6. `cfi-cli deploy`

4. Bank Onboarding & Integration Sandbox CLI (`scripts/cfi_cli.py`)

4.1. `python scripts/cfi_cli.py init`

4.2. `python scripts/cfi_cli.py cert generate-csr`

4.3. `python scripts/cfi_cli.py test-connection`

4.4. `python scripts/cfi_cli.py sandbox run`