Multi-Cloud Non-Human Identity (NHI) Risk Analyzer & Remediator

An enterprise-grade, offline-first security automation platform that discovers, inventories, analyzes, risk-assesses, and safely remediates Non-Human Identities (NHIs) — service principals, service accounts, machine roles, access keys, and credentials — across AWS, Azure, and Google Cloud Platform (GCP).

⭐️ If you find this tool helpful for auditing and securing Non-Human Identities across clouds, please consider starring the repository!

---

🌐 Multi-Cloud Identity Coverage

Cloud Provider	Identity Types Covered	Discovery Engine	Secret / Credential Inspection	Rules Active	Status
🟧 AWS	IAM Roles, Machine Users, Groups, Policies	Boto3 + Session Caching	Access Keys (CreateDate, LastUsed)	13 Rules (AWS_01–16, TAG_01)	✅ Supported
🟦 Azure	Entra ID Service Principals, App Registrations, Managed Identities	Pure REST (Graph & ARM)	Client Secrets (passwordCredentials), Certs (keyCredentials)	5 Rules (AZURE_01–05)	✅ Supported
🟥 GCP	Service Accounts, Workload Identity, IAM Roles	Pure REST (IAM & Resource Mgr)	Service Account Keys (validAfterTime, user-managed)	6 Rules (GCP_01–06)	✅ Supported

🧪 Test Suite Status: 102 passed, 4 subtests passed (100% GREEN) across all providers and engines.

---

📋 Overview

NHI Risk Analyzer addresses a critical multi-cloud security challenge: modern enterprise cloud environments accumulate hundreds of machine and non-human identities (service accounts, automation roles, CI/CD credentials, cross-cloud trust roles) with minimal visibility into which identities are over-privileged, dormant, or introduce privilege-escalation risk.

The platform enforces strict architectural decoupling across three distinct phases:

1. Multi-Cloud State Collection: Ingestion into a normalized inventory.json snapshot via lightweight, cloud-native mechanisms (Boto3 session-cached for AWS; zero-dependency pure REST for Azure and GCP).
2. Offline Risk Evaluation: Evaluating security rules against the snapshot without live network dependencies. This means the risk engine can be re-run, tested, and iterated on without touching cloud providers again, and every finding is reproducible against the exact account/tenant state it was generated from.
3. Automated Remediation & Containment: A fail-closed containment pipeline that neutralizes dangerous escalation attack paths via policy boundaries and deactivates stale/dormant credentials without causing operational microservice outages.

---

🎯 Why This Project Exists

Enterprise multi-cloud environments routinely contain non-human identities that are:

• Unstandardized: Created manually across disparate clouds without unified provisioning standards.
• Over-Permissioned: Granted administrative or wildcard permissions far exceeding actual operational needs.
• Dormant & Forgotten: Left active long after workloads or integration pipelines have been decommissioned.
• Incompletely Audited: Carrying inline policies, custom role definitions, or direct bindings that bypass standard compliance checks.
• Credential Risks: Utilizing access keys, client secrets, or service account keys that are stale (>90 days old), expiring, or have never been used since inception.
• Escalation-Prone: Holding cloud IAM permissions that, alone or combined, allow privilege escalation to full administrator access — documented attack paths that most policy-only scanners don't check for.

NHI Risk Analyzer automates discovery, security analysis, and targeted remediation across cloud providers using cloud APIs and offline rule processing.

---

🏗️ Architecture & Workflow

  ┌──────────────┐         ┌──────────────┐         ┌──────────────┐
  │   AWS IAM    │         │  Azure Entra │         │   GCP IAM    │
  │   (Boto3)    │         │  (Pure REST) │         │  (Pure REST) │
  └──────┬───────┘         └──────┬───────┘         └──────┬───────┘
         │                        │                        │
         └────────────────┐       │       ┌────────────────┘
                          ▼       ▼       ▼
                    ┌───────────────────────────┐
                    │       inventory.py        │
                    │ (Multi-Cloud Collector)   │
                    └─────────────┬─────────────┘
                                  ▼
                    ┌───────────────────────────┐
                    │      inventory.json       │
                    │  (Unified State Snapshot) │
                    └─────────────┬─────────────┘
                                  │
                                  ▼
                    ┌───────────────────────────┐
                    │          risk.py          │
                    │    (--cloud Orchestrator) │
                    └─────────────┬─────────────┘
                                  │
         ┌────────────────────────┼────────────────────────┐
         ▼                        ▼                        ▼
  ┌──────────────┐         ┌──────────────┐         ┌──────────────┐
  │  aws.py sub- │         │ azure.py sub-│         │  gcp.py sub- │
  │    runner    │         │    runner    │         │    runner    │
  │ (13 Rules)   │         │  (5 Rules)   │         │  (6 Rules)   │
  └──────┬───────┘         └──────┬───────┘         └──────┬───────┘
         └────────────────────────┼────────────────────────┘
                                  ▼
                    ┌───────────────────────────┐
                    │        dispatch.py        │
                    │ (Containment Dispatcher)  │
                    └─────────────┬─────────────┘
                                  │
         ┌────────────────────────┴────────────────────────┐
         ▼                                                 ▼
┌─────────────────────────┐                     ┌─────────────────────┐
│ policy_surgery.py &     │                     │    credential.py    │
│ policy.py (Boundaries)  │                     │ (Deactivate Key)    │
└─────────────────────────┘                     └─────────────────────┘

1. State Collection (nhi/services/inventory.py): Queries cloud APIs across AWS, Azure, and GCP, enriches credential metadata (access key last-used, secret expiration), and serializes a clean state snapshot to inventory.json.
2. Selective Cloud Orchestrator (nhi/risk/risk.py): Accepts --cloud {aws,azure,gcp,all} to selectively target cloud providers, saving unnecessary API calls and avoiding cross-tenant rate limits.
3. Modular Risk Runners (nhi/risk/runners/): Decoupled execution engines (aws.py, azure.py, gcp.py) process provider inventories against modular security rules with defensive guards against partial or missing cloud payloads.
4. Artifact Export & Run-over-Run Diffing (nhi/services/export.py, nhi/remediation/diff.py): Calculates security drift against historical baseline scans, uploads execution artifacts to cloud storage, and exports findings to CSV and OASIS SARIF v2.1.0 for audit pipelines.
5. Remediation & Policy Surgery (nhi/remediation/): AST-level policy statement partitioning (policy_surgery.py) and non-destructive containment boundaries/key deactivation with dry-run simulation mode and nhi-ignore.yaml exemptions.

---

⚡ Engineering Optimizations

AWS Session Caching

To eliminate redundant AWS STS authentication calls during inventory collection, authenticated boto3.Session objects are cached for the lifetime of the Python process in nhi/aws/session.py.

• STS AssumeRole calls reduced: 35 → 1
• Inventory execution time reduced: 79.58s → 45.67s (~43% runtime improvement)
• Encapsulation: Authentication remains fully encapsulated inside session.py, requiring zero logic changes to discovery or rule modules.