ic-code 1.7.1__tar.gz → 1.7.2__tar.gz

ic_code-1.7.2/PKG-INFO

@@ -0,0 +1,688 @@
+Metadata-Version: 2.4
+Name: ic-code
+Version: 1.7.2
+Summary: Infrastructure CLI tool for managing AWS, Tencent Cloud, GCP, OCI, CloudFlare, SSH, and more
+Author-email: sykim <cruiser594@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/dgr009/ic
+Project-URL: Bug Reports, https://github.com/dgr009/ic/issues
+Project-URL: Source, https://github.com/dgr009/ic
+Project-URL: Documentation, https://github.com/dgr009/ic#readme
+Keywords: cli,infrastructure,aws,oci,gcp,cloudflare,ssh,devops,multi-cloud
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Utilities
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Environment :: Console
+Requires-Python: <3.14,>=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests<3.0.0,>=2.31.0
+Requires-Dist: cryptography<50.0.0,>=42.0.0
+Requires-Dist: rich<15.0.0,>=13.0.0
+Requires-Dist: InquirerPy<1.0.0,>=0.3.4
+Requires-Dist: tqdm<5.0.0,>=4.67.0
+Requires-Dist: python-dotenv<2.0.0,>=1.0.0
+Requires-Dist: python-dateutil<3.0.0,>=2.9.0
+Requires-Dist: PyYAML<7.0.0,>=6.0.1
+Requires-Dist: click<9.0.0,>=8.1.0
+Requires-Dist: docutils<1.0.0,>=0.19
+Requires-Dist: invoke<3.0.0,>=2.2.0
+Requires-Dist: jsonschema<5.0.0,>=4.23.0
+Requires-Dist: watchdog<6.0.0,>=4.0.0
+Requires-Dist: cerberus<2.0.0,>=1.3.5
+Requires-Dist: pydantic<3.0.0,>=2.7.0
+Requires-Dist: packaging<25.0,>=24.0
+Requires-Dist: setuptools<76.0.0,>=69.0.0
+Provides-Extra: aws
+Requires-Dist: boto3<2.0.0,>=1.34.0; extra == "aws"
+Requires-Dist: botocore<2.0.0,>=1.34.0; extra == "aws"
+Requires-Dist: awscli<2.0.0,>=1.32.0; extra == "aws"
+Provides-Extra: tencent
+Requires-Dist: tencentcloud-sdk-python<4.0.0,>=3.0.0; extra == "tencent"
+Provides-Extra: oci
+Requires-Dist: oci<3.0.0,>=2.149.0; extra == "oci"
+Provides-Extra: gcp
+Requires-Dist: google-cloud-compute<2.0.0,>=1.36.0; extra == "gcp"
+Requires-Dist: google-cloud-container<3.0.0,>=2.44.0; extra == "gcp"
+Requires-Dist: google-cloud-storage<3.0.0,>=2.18.0; extra == "gcp"
+Requires-Dist: google-cloud-functions<2.0.0,>=1.16.0; extra == "gcp"
+Requires-Dist: google-cloud-run<1.0.0,>=0.11.0; extra == "gcp"
+Requires-Dist: google-cloud-billing<2.0.0,>=1.13.0; extra == "gcp"
+Requires-Dist: google-cloud-dns<1.0.0,>=0.34.0; extra == "gcp"
+Requires-Dist: google-cloud-resource-manager<2.0.0,>=1.12.0; extra == "gcp"
+Requires-Dist: google-auth<3.0.0,>=2.29.0; extra == "gcp"
+Requires-Dist: google-auth-oauthlib<2.0.0,>=1.2.0; extra == "gcp"
+Requires-Dist: google-auth-httplib2<1.0.0,>=0.2.0; extra == "gcp"
+Provides-Extra: ssh
+Requires-Dist: paramiko<5.0.0,>=3.4.0; extra == "ssh"
+Requires-Dist: netifaces<1.0.0,>=0.11.0; extra == "ssh"
+Provides-Extra: k8s
+Requires-Dist: kubernetes<32.0.0,>=29.0.0; extra == "k8s"
+Provides-Extra: all
+Requires-Dist: boto3<2.0.0,>=1.34.0; extra == "all"
+Requires-Dist: botocore<2.0.0,>=1.34.0; extra == "all"
+Requires-Dist: awscli<2.0.0,>=1.32.0; extra == "all"
+Requires-Dist: tencentcloud-sdk-python<4.0.0,>=3.0.0; extra == "all"
+Requires-Dist: oci<3.0.0,>=2.149.0; extra == "all"
+Requires-Dist: google-cloud-compute<2.0.0,>=1.36.0; extra == "all"
+Requires-Dist: google-cloud-container<3.0.0,>=2.44.0; extra == "all"
+Requires-Dist: google-cloud-storage<3.0.0,>=2.18.0; extra == "all"
+Requires-Dist: google-cloud-functions<2.0.0,>=1.16.0; extra == "all"
+Requires-Dist: google-cloud-run<1.0.0,>=0.11.0; extra == "all"
+Requires-Dist: google-cloud-billing<2.0.0,>=1.13.0; extra == "all"
+Requires-Dist: google-cloud-dns<1.0.0,>=0.34.0; extra == "all"
+Requires-Dist: google-cloud-resource-manager<2.0.0,>=1.12.0; extra == "all"
+Requires-Dist: google-auth<3.0.0,>=2.29.0; extra == "all"
+Requires-Dist: google-auth-oauthlib<2.0.0,>=1.2.0; extra == "all"
+Requires-Dist: google-auth-httplib2<1.0.0,>=0.2.0; extra == "all"
+Requires-Dist: paramiko<5.0.0,>=3.4.0; extra == "all"
+Requires-Dist: netifaces<1.0.0,>=0.11.0; extra == "all"
+Requires-Dist: kubernetes<32.0.0,>=29.0.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest<10.0.0,>=8.0.0; extra == "dev"
+Requires-Dist: pytest-cov<8.0.0,>=5.0.0; extra == "dev"
+Requires-Dist: types-PyYAML>=6.0.0; extra == "dev"
+Requires-Dist: black<25.0.0,>=24.0.0; extra == "dev"
+Requires-Dist: flake8<8.0.0,>=7.0.0; extra == "dev"
+Requires-Dist: mypy<2.0.0,>=1.10.0; extra == "dev"
+Requires-Dist: pyrefly>=1.2.0; extra == "dev"
+Requires-Dist: pre-commit<4.0.0,>=3.7.0; extra == "dev"
+Dynamic: license-file
+
+# IC CLI Tool (Infrastructure Commander)
+
+[![PyPI version](https://badge.fury.io/py/ic-code.svg)](https://badge.fury.io/py/ic-code)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A production-grade Multi-Cloud & Infrastructure Command Line Interface for inspecting, auditing, and managing cloud resources across **AWS**, **Tencent Cloud**, **Google Cloud Platform (GCP)**, **Oracle Cloud Infrastructure (OCI)**, **CloudFlare**, and **SSH** servers from a single unified terminal workflow.
+
+---
+
+## Table of Contents
+
+1. [Key Features](#key-features)
+2. [Terminal UI & Output Previews](#terminal-ui--output-previews)
+3. [Supported Platforms & Services](#supported-platforms--services)
+4. [Installation & Initial Setup](#installation--initial-setup)
+5. [Platform Credential & Configuration Guide](#platform-credential--configuration-guide)
+6. [Command Usage Examples](#command-usage-examples)
+7. [Testing & Verification](#testing--verification)
+8. [License](#license)
+
+---
+
+## Key Features
+
+- **Unified Multi-Cloud CLI**: Consistent `<platform> <service> <command>` syntax across AWS, Tencent Cloud, GCP, OCI, CloudFlare (`cloudflare` / `cf`), and SSH servers.
+- **Smart Auth & Profile Switcher**: One-command atomic switching between personal SSO/STS sessions (`aws login`, `tccli auth login`) and static service account credentials, with real-time STS token expiration tracking and automatic file permission enforcement (`chmod 600`).
+- **Deep IAM & CAM Permission Governance**:
+  - **Credential Hygiene (`iam check` / `cam check`)**: Audit console login status, MFA enforcement, password age (60/90-day risk alerts), last console login, and last access key usage.
+  - **Entity Permission Mapping (`iam user` / `cam user`)**: Inspect user groups, direct/inline/group-inherited policies, scoped resources, IP/MFA/tag conditions (`aws:SourceIp`, `qcs:ip`), and linked roles.
+  - **Policy & Role Analysis (`iam policy|role` / `cam policy|role`)**: Inspect AWS/Tencent managed, custom, and inline policies, attached entities (Users/Groups/Roles), role trust principals, trust conditions (`sts:ExternalId`), and raw policy documents (`-d`).
+- **Concurrent Multi-Account & Multi-Region Execution**: Parallel resource discovery across dozens of cloud accounts/projects and regions simultaneously using `ThreadPoolExecutor` and cross-account `AssumeRole`.
+- **Multiple Output Representations**:
+  - **Rich Tables (`-o table`)**: Color-coded status indicators, aligned columns, and account/region grouping.
+  - **Hierarchical Trees (`-o tree`)**: Visual dependency and rule trees for Security Groups, Firewalls, IAM/CAM permissions, and GCP folder hierarchies.
+  - **Deep Schema Discovery (`desc -l`, `desc -k`)**: Inspect raw cloud resource schemas and extract nested attributes using dot-notation keys.
+  - **Spreadsheet Copy Mode (`-p`)**: Clean comma-separated output for instant copy-pasting into spreadsheets or incident reports.
+- **Security First**: Split configuration architecture (`default.yaml` + `secrets.yaml`), automatic credential masking in logs/CLI output, built-in secret scanner (`ic security scan`), and pre-commit hook integration.
+
+---
+
+## Terminal UI & Output Previews
+
+### 1. Multi-Account Compute Inspection (`ic tencent cvm info` / `ic aws ec2 info`)
+
+![Tencent CVM Info Terminal UI](docs/tencent/use_sample.png)
+
+```text
+$ ic aws ec2 info -a prod-account -r ap-northeast-2 -n api,worker
+┌──────────────┬────────────────┬────────────────────┬─────────────────────┬─────────┬───────────┬──────┬────────┬───────────────┬───────────────┬──────────────────────┬────────────┐
+│ Account      │ Region         │ Instance Name      │ Instance ID         │ State   │ Type      │ vCPU │ Memory │ Private IP    │ Public IP     │ Security Groups      │ Created    │
+├──────────────┼────────────────┼────────────────────┼─────────────────────┼─────────┼───────────┼──────┼────────┼───────────────┼───────────────┼──────────────────────┼────────────┤
+│ prod-account │ ap-northeast-2 │ prod-api-server-01 │ i-0a1b2c3d4e5f60001 │ running │ m6i.large │ 2    │ 8 GiB  │ 10.20.1.15    │ 203.0.113.10  │ sg-0100 (prod-api)   │ 2026-03-15 │
+│ prod-account │ ap-northeast-2 │ prod-worker-node01 │ i-0a1b2c3d4e5f60002 │ running │ c6i.xlarge│ 4    │ 8 GiB  │ 10.20.2.42    │ -             │ sg-0200 (prod-batch) │ 2026-04-02 │
+└──────────────┴────────────────┴────────────────────┴─────────────────────┴─────────┴───────────┴──────┴────────┴───────────────┴───────────────┴──────────────────────┴────────────┘
+```
+
+### 2. IAM / CAM User Permission, Resource & Condition Mapping (`ic aws iam user`)
+
+```text
+$ ic aws iam user -a prod-account -n deploy,sre
+┌──────────────┬──────────────┬────────────┬──────────────┬───────────────────────────────────────────┬────────────────────────────────────────────────────────┬─────────────────────────────┐
+│ Account      │ User Name    │ Login Type │ Groups       │ Attached Policies                         │ Scoped Resources / Conditions                          │ Linked / Trusted Roles      │
+├──────────────┼──────────────┼────────────┼──────────────┼───────────────────────────────────────────┼────────────────────────────────────────────────────────┼─────────────────────────────┤
+│ prod-account │ sre-operator │ User (MFA) │ sre-admins   │ [Group:sre-admins] AdministratorAccess    │ [IpRestrictInline]                                     │ ProdEksClusterAdminRole     │
+│              │              │            │              │ [Inline] IpRestrictInline                 │   Cond: IpAddress: aws:SourceIp=203.0.113.0/24         │   (Cond: aws:MultiFactor... │
+│ prod-account │ ci-deployer  │ Service    │ -            │ [Managed] AmazonEC2ContainerRegistryPower │ [S3ArtifactDeployPolicy]                               │ ProdAppDeployRole           │
+│              │              │            │              │ [Inline] S3ArtifactDeployPolicy           │   Res: s3: prod-artifact-bucket, prod-artifact-buck... │                             │
+└──────────────┴──────────────┴────────────┴──────────────┴───────────────────────────────────────────┴────────────────────────────────────────────────────────┴─────────────────────────────┘
+```
+
+### 3. Credential Hygiene & Password Age Audit (`ic aws iam check -w`)
+
+```text
+$ ic aws iam check -a prod-account -w
+┌──────────────┬──────────────┬───────────────┬─────────┬──────────────┬────────────┬──────────────────┬──────────────────┬────────────┐
+│ Account      │ User Name    │ Console Login │ MFA     │ Password Age │ Last Login │ Active Keys      │ Last Key Used    │ Created    │
+├──────────────┼──────────────┼───────────────┼─────────┼──────────────┼────────────┼──────────────────┼──────────────────┼────────────┤
+│ prod-account │ legacy-admin │ Enabled       │ Enabled │ 114d (Warn)  │ 2026-09-10 │ 1 (98d)          │ 2026-10-28 (ecr) │ 2024-05-12 │
+│ prod-account │ build-bot    │ Disabled      │ -       │ -            │ -          │ 1 (142d) (Warn)  │ 2026-11-01 (s3)  │ 2024-08-01 │
+└──────────────┴──────────────┴───────────────┴─────────┴──────────────┴────────────┴──────────────────┴──────────────────┴────────────┘
+```
+
+### 4. Hierarchical Tree View (`-o tree`)
+
+```text
+$ ic aws sg info -a prod-account -n prod-api -o tree
+AWS Security Groups (prod-account / ap-northeast-2)
+└── prod-api-sg (sg-0100aabbccddeeff0) [vpc-0a1b2c3d]
+    ├── [Ingress] TCP 443 ← 0.0.0.0/0 (HTTPS public traffic)
+    ├── [Ingress] TCP 8080 ← sg-0050alb0000000001 (From ALB ingress)
+    └── [Egress]  ALL ALL → 0.0.0.0/0 (Allow outbound)
+
+$ ic tencent cam user -a prod-account -n devops -o tree
+Tencent CAM Users
+└── prod-account (100000000001)
+    └── devops-engineer [Type: User | Created: 2025-11-20]
+        ├── Groups: devops-team
+        ├── Attached Policies (3)
+        │   ├── [Direct] QcloudCVMFullAccess (QCS)
+        │   ├── [Group:devops-team] QcloudCLBFullAccess (QCS)
+        │   └── [Direct] CustomProdVpcReadOnly (Custom)
+        │       ├── Resources: vpc: ap-seoul/vpc-sample01
+        │       └── Conditions: ip_equal: qcs:ip=203.0.113.10/32
+        └── Trusted Roles (1)
+            └── ProdTkeClusterAdminRole
+```
+
+### 5. Spreadsheet Copy-Paste Mode (`-p`)
+
+```text
+$ ic tencent cvm info -a prod-account -p
+Account,Region,InstanceName,InstanceId,State,InstanceType,CPU,Memory(GB),PrivateIP,PublicIP,VPC,SecurityGroups,CreatedTime
+prod-account,ap-seoul,prod-web-01,ins-a1b2c3d4,RUNNING,S5.LARGE8,4,8,10.10.1.11,198.51.100.25,vpc-sample01,sg-web01,2026-02-10 14:20:00
+prod-account,ap-seoul,prod-db-01,ins-e5f6g7h8,RUNNING,S5.2XLARGE32,8,32,10.10.2.20,-,vpc-sample01,sg-db01,2026-02-10 14:25:00
+```
+
+---
+
+## Supported Platforms & Services
+
+### 1. AWS Services
+| Category | Commands | Description |
+|---|---|---|
+| **Auth & Profile** | `ic aws profile switch`, `ic aws profile info` | Atomic switching between personal `aws login` STS session and static service credentials; session expiry tracking. |
+| **IAM & Governance** | `ic aws iam check`, `ic aws iam user`, `ic aws iam policy`, `ic aws iam role` | Password/key hygiene audit (`check`), user group/policy/role/condition mapping (`user`), managed & inline policy inspection (`policy`), and role trust/policy analysis (`role`). |
+| **EC2 Compute** | `ic aws ec2 info`, `ic aws ec2 desc` | Instance inventory across accounts/regions, spreadsheet copy mode (`-p`), and dot-notation schema inspection (`desc -l`, `desc -k`). |
+| **Containers (EKS / ECS)** | `ic aws eks info\|nodes\|pods\|addons\|fargate`, `ic aws ecs info\|service\|task` | Kubernetes clusters, node groups, pods, addons, Fargate profiles, and ECS clusters/services/tasks. |
+| **Storage & Databases** | `ic aws ebs info`, `ic aws s3 info\|tag_check`, `ic aws rds info` | EBS volume metrics, S3 bucket inventory & tag compliance auditing, RDS & Aurora cluster inspection. |
+| **Networking & Security** | `ic aws vpc info`, `ic aws vpn info`, `ic aws lb info\|desc`, `ic aws sg info`, `ic aws cloudfront info` | VPCs/Subnets/NAT/VPN, ALB/NLB listener rules & target health, Security Group rules & tree view (`-o tree`), CloudFront distributions. |
+| **Health & Integrations** | `ic aws healthdashboard reboot`, `ic aws msk info\|broker`, `ic aws codepipeline build\|deploy` | Multi-account EC2 scheduled reboot maintenance checks, MSK Kafka clusters, and CodePipeline status. |
+
+### 2. Tencent Cloud Services
+| Category | Commands | Description |
+|---|---|---|
+| **Auth & Profile** | `ic tencent profile switch`, `ic tencent profile info` | Dual-mode switching between personal `tccli auth login` STS session and `~/.tencent/credentials` service keys with cross-account `AssumeRole`. |
+| **CAM & Governance** | `ic tencent cam check`, `ic tencent cam user`, `ic tencent cam policy`, `ic tencent cam role` | Sub-account & collaborator password/key audit (`check`), user group/policy/resource/condition/role mapping (`user`), Custom & QCS policy analysis (`policy`), and CAM role trust inspection (`role`). |
+| **CVM & Lighthouse** | `ic tencent cvm info\|desc`, `ic tencent lighthouse info\|firewall` | CVM instances, creation date filter (`-c`), spreadsheet copy mode (`-p`), deep attribute inspection (`desc`), Lighthouse instances & firewall trees (`-o tree`). |
+| **Containers (TKE)** | `ic tencent tke info` | TKE Kubernetes clusters, versions, status, and node pool configurations. |
+| **Storage (CBS)** | `ic tencent cbs info`, `ic tencent disk info` | Cloud Block Storage volume size, type, attachment status, and linked CVM instances. |
+| **Networking & CLB** | `ic tencent clb info\|desc\|traffic`, `ic tencent sg info`, `ic tencent vpc info`, `ic tencent nat info` | CLB listener rules & target health, 7/30-day bandwidth & traffic stats (`clb traffic`), Security Group rules & tree view (`-o tree`), VPCs, Subnets, and NAT Gateways. |
+
+### 3. Google Cloud Platform (GCP) Services
+| Category | Commands | Description |
+|---|---|---|
+| **Compute & LB** | `ic gcp compute info\|desc`, `ic gcp lb info\|desc` | Compute Engine VMs (summary & 15-column `-v` view), Forwarding Rules, Target Proxies, URL Maps, Backend Services, and dot-notation schema inspection (`desc`). |
+| **Containers & Serverless** | `ic gcp gke info`, `ic gcp run info`, `ic gcp functions info` | GKE clusters & node pools, Cloud Run services/revisions, 1st & 2nd Gen Cloud Functions. |
+| **Storage & Databases** | `ic gcp sql info`, `ic gcp storage info` | Cloud SQL (MySQL/PostgreSQL/SQL Server) HA/backup status and GCS bucket inventory. |
+| **Networking & DNS** | `ic gcp vpc info`, `ic gcp firewall info`, `ic gcp dns info` | VPC networks/subnets, Ingress/Egress firewall rules, and Cloud DNS managed zones. |
+| **Projects & Billing** | `ic gcp project info`, `ic gcp billing info`, `ic gcp profile info` | Multi-level folder/project hierarchy tree, monthly billing breakdown, and active `gcloud` configurations. |
+
+### 4. Oracle Cloud Infrastructure (OCI), CloudFlare & SSH
+| Platform | Commands | Description |
+|---|---|---|
+| **OCI** | `ic oci vm info`, `ic oci aci info`, `ic oci vcn info`, `ic oci lb info`, `ic oci nsg info`, `ic oci volume info`, `ic oci obj info`, `ic oci compartment`, `ic oci policy info\|search`, `ic oci cost usage\|credit` | OCI Compute VMs, Autonomous Container Instances, VCNs, Load Balancers, NSGs, Block/Object Storage, Compartment trees, IAM Policies, and Cost/Billing credits. |
+| **CloudFlare** | `ic cf zone info`, `ic cf dns info` (or `ic cloudflare ...`) | CloudFlare Zone inventory and DNS record inspection with account/zone filtering. |
+| **SSH Server** | `ic ssh info` | Automatic server discovery from `~/.ssh/config`, parallel SSH connectivity & port checks, and configurable host key policies (`auto`, `warning`, `reject`). |
+
+---
+
+## Installation & Initial Setup
+
+### 1. Requirements
+
+- **Python**: `>= 3.9, < 3.14` (Python 3.11 or 3.13 recommended)
+- **OS**: macOS, Linux, or Windows (WSL2 / PowerShell)
+- **Optional Cloud CLI Tools** (only required if using native CLI SSO login features):
+  - AWS CLI v2 (`aws login` / `aws sso login`)
+  - Tencent Cloud CLI (`tccli auth login`)
+  - Google Cloud SDK (`gcloud auth application-default login`)
+
+### 2. Install from PyPI (Recommended)
+
+You can install the lightweight core package or include optional cloud SDK extras for the platforms you manage:
+
+```bash
+# Install core package + default dependencies
+pip install ic-code
+
+# Or install with specific cloud platform SDK extras
+pip install "ic-code[aws]"          # AWS (boto3)
+pip install "ic-code[tencent]"      # Tencent Cloud SDK
+pip install "ic-code[gcp]"          # Google Cloud SDK libraries
+pip install "ic-code[oci]"          # Oracle Cloud Infrastructure SDK
+pip install "ic-code[cloudflare]"   # CloudFlare API support
+pip install "ic-code[ssh]"          # SSH management (paramiko)
+
+# Install all cloud platform extras at once
+pip install "ic-code[all]"
+
+# Verify installation
+ic --version
+ic --help
+```
+
+> **Tip (Isolated Global CLI Installation with `pipx`)**:
+> ```bash
+> pipx install "ic-code[all]"
+> ```
+
+### 3. Install from Source (Development)
+
+```bash
+# Clone the repository
+git clone https://github.com/dgr009/ic.git
+cd ic
+
+# Create and activate a virtual environment
+python3 -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+
+# Install in editable mode with all cloud and test dependencies
+pip install --upgrade pip
+pip install -r requirements.txt
+pip install -e .
+
+# Verify CLI execution
+ic --version
+ic --help
+```
+
+---
+
+## Platform Credential & Configuration Guide
+
+IC CLI separates non-sensitive preferences from sensitive credentials using a two-file structure under `~/.ic/config/`:
+
+```text
+~/.ic/config/
+├── default.yaml        # Non-sensitive settings (default regions, worker counts, logging, SSH host policy)
+└── secrets.yaml        # Sensitive tokens, account mappings, and role names (chmod 600 recommended)
+```
+
+### Step 1: Initialize Configuration Files
+
+```bash
+# Interactive setup wizard
+ic config init
+
+# Or generate a template for a specific workflow
+ic config init --template aws
+ic config init --template multi-cloud
+
+# Validate configuration and inspect masked settings
+ic config validate
+ic config show
+```
+
+### Step 2: Configure Cloud Credentials
+
+#### A. AWS Credential Setup (`~/.aws/config` & `~/.aws/credentials`)
+
+IC CLI automatically reads standard AWS profiles from `~/.aws/config` and `~/.aws/credentials`, and supports one-touch switching between personal STS sessions (`aws login`) and service account keys (`~/.aws/backup/`):
+
+```ini
+# ~/.aws/config
+[profile prod-account]
+region = ap-northeast-2
+output = json
+
+[profile stage-account]
+role_arn = arn:aws:iam::234567890123:role/OrganizationAccountAccessRole
+source_profile = prod-account
+region = ap-northeast-2
+```
+
+```bash
+# Check active AWS profiles and STS token status
+ic aws profile info
+ic aws profile switch
+```
+
+#### B. Tencent Cloud Credential Setup (`~/.tencent/credentials` & `secrets.yaml`)
+
+IC CLI supports both multi-account `~/.tencent/credentials` (with cross-account `AssumeRole`) and personal `tccli auth login` sessions:
+
+```ini
+# ~/.tencent/credentials
+[default]
+region = ap-seoul
+
+[main]
+secret_id = AKIDEXAMPLE000000000000000000000
+secret_key = EXAMPLESECRETKEY0000000000000000
+region = ap-seoul
+
+[prod-account]
+role_arn = qcs::cam::uin/100000000002:roleName/OrganizationAccountAccessRole
+source_account = main
+region = ap-seoul
+```
+
+```bash
+# Check active Tencent Cloud authentication mode and accounts
+ic tencent profile info
+ic tencent profile switch
+```
+
+#### C. GCP, OCI, CloudFlare & SSH Setup
+
+- **GCP**: Authenticate via Application Default Credentials:
+  ```bash
+  gcloud auth application-default login
+  ```
+- **OCI**: Configure standard `~/.oci/config` with your tenancy OCID, user OCID, fingerprint, and private key path.
+- **CloudFlare & Multi-Cloud Options (`~/.ic/config/secrets.yaml`)**:
+
+```yaml
+# ~/.ic/config/secrets.yaml (Sample - use generic or local values only)
+aws:
+  accounts:
+    - "prod-account"
+    - "stage-account"
+  regions:
+    - "ap-northeast-2"
+    - "us-east-1"
+
+tencent:
+  root_account: "main"
+  root_account_id: "100000000001"
+  tccli_role: "OrganizationAccountAccessRole"
+  service_role: "ServiceAdminRole"
+  isolated_accounts:
+    - "isolated-sub-account"
+  regions:
+    - "ap-seoul"
+    - "ap-singapore"
+
+gcp:
+  project_id: "sample-gcp-project-01"
+  regions:
+    - "asia-northeast3"
+    - "us-central1"
+
+oci:
+  config_file: "~/.oci/config"
+  profile: "DEFAULT"
+
+cloudflare:
+  email: "admin@example.com"
+  api_token: "your-cloudflare-api-token"
+  cloudflare_accounts:
+    - "Sample-Account"
+  cloudflare_zones:
+    - "example.com"
+
+ssh:
+  config_file: "~/.ssh/config"
+  key_dir: "~/.ssh"
+  host_key_policy: "auto"
+  skip_prefixes:
+    - "git"
+    - "bastion-"
+```
+
+---
+
+## Command Usage Examples
+
+### Common Filtering & Output Options
+
+Most resource inspection commands share consistent filtering flags:
+
+| Flag | Description | Example |
+|---|---|---|
+| `-a, --account <NAME>` | Filter by account/profile/project name (comma-separated for multiple) | `-a prod-account,stage-account` |
+| `-r, --region <REGION>` | Filter by cloud region (comma-separated) | `-r ap-northeast-2,us-east-1` |
+| `-n, --name <PATTERN>` | Case-insensitive partial match filter (comma-separated for OR search) | `-n "api,worker"` |
+| `-c, --created <EXPR>` | Filter by creation date (`YYYY-MM-DD`, range `~`, `>=`, `<=`, `>`, `<`) | `-c ">=2026-01-01"` |
+| `-o, --output <FMT>` | Output format (`table`, `tree`, `json`, `yaml`) | `-o tree` |
+| `-v, --verbose` | Show extended columns, full ARNs, or full resource lists without truncation | `-v` |
+| `-p, --paste` | Output clean comma-separated values for spreadsheet copy-pasting | `-p` |
+
+---
+
+### 1. AWS Command Examples
+
+```bash
+# --- Authentication & Profile Management ---
+ic aws profile info                                         # Inspect all profiles and session status
+ic aws profile switch                                       # Check current auth mode (login vs service)
+ic aws profile switch login                                 # Switch to personal 'aws login' STS session
+ic aws profile switch service                               # Switch to static service credentials
+
+# --- IAM Security Audit & Permission Governance ---
+# 1) Credential & Password Hygiene Audit (check)
+ic aws iam check                                            # Audit console login, MFA, password age, key usage
+ic aws iam check -w                                         # Filter accounts with 90+ day warnings
+ic aws iam check --mfa disabled -t user                     # Find console users without MFA enabled
+ic aws iam check -c ">=2026-01-01" -v                       # Filter by creation date with verbose key IDs
+
+# 2) User Permission, Resource & Condition Inspection (user)
+ic aws iam user                                             # Inspect users, groups, policies, resources/conditions, roles
+ic aws iam user -a prod-account -n deploy,admin             # Filter by account and user name patterns
+ic aws iam user -g sre-admins --policy AdministratorAccess  # Filter by group or attached policy name
+ic aws iam user --resource s3 --condition 203.0.113.0/24    # Find users restricted by specific resource or IP condition
+ic aws iam user -o tree                                     # Render user permission hierarchy as a tree
+
+# 3) IAM Policy Inspection (policy)
+ic aws iam policy                                           # List customer-managed and inline policies
+ic aws iam policy -t custom --attached                      # Show only attached customer-managed policies
+ic aws iam policy -t inline --entity sre-operator           # Show inline policies attached to a specific entity
+ic aws iam policy --unattached                              # Identify unused policies for cleanup
+ic aws iam policy -n DeployPolicy --resource bucket -d      # Print full JSON policy statement document (-d)
+
+# 4) IAM Role & Trust Relationship Inspection (role)
+ic aws iam role                                             # List IAM roles, trusted principals, and attached policies
+ic aws iam role -t user --no-slr                            # Show cross-account/user roles excluding Service-Linked Roles
+ic aws iam role --trust ec2,eks --policy Admin              # Filter by trusted service/principal and policy
+ic aws iam role --condition ExternalId -o tree              # Inspect roles requiring ExternalId in tree view
+
+# --- EC2, Containers & Maintenance ---
+ic aws healthdashboard reboot                               # Check scheduled EC2 reboot maintenance across all accounts
+ic aws healthdashboard reboot -a prod-account --all-status  # Include historical/completed maintenance events
+
+ic aws ec2 info -a prod-account -n "web,api"                # List EC2 instances matching 'web' or 'api'
+ic aws ec2 info -p                                          # Output EC2 inventory in spreadsheet copy format
+ic aws ec2 desc -l                                          # List queryable EC2 dot-notation schema keys
+ic aws ec2 desc -k InstanceId,State.Name,PrivateIpAddress   # Extract specific EC2 attributes
+
+ic aws eks info                                             # List EKS clusters
+ic aws eks nodes -a prod-account                            # Inspect EKS node groups
+ic aws eks pods -a prod-account                             # Inspect EKS pods across namespaces
+ic aws ecs info                                             # List ECS clusters, services, and tasks
+
+# --- Storage, Databases & Networking ---
+ic aws ebs info -a prod-account                             # Inspect EBS volumes, IOPS, throughput, and attachments
+ic aws s3 info                                              # List S3 buckets
+ic aws s3 tag_check                                         # Audit S3 buckets for required compliance tags
+ic aws rds info                                             # Inspect RDS instances and Aurora clusters
+
+ic aws sg info -a prod-account                              # Inspect Security Group ingress/egress rules
+ic aws sg info -a prod-account -o tree                      # Render Security Group rules as a visual hierarchy tree
+ic aws lb info -a prod-account                              # Inspect ALB/NLB listeners, rules, and target health
+ic aws vpc info -a prod-account                             # Inspect VPCs, Subnets, and NAT Gateways
+ic aws cloudfront info                                      # Inspect CloudFront CDN distributions
+```
+
+---
+
+### 2. Tencent Cloud Command Examples
+
+```bash
+# --- Authentication & Profile Management ---
+ic tencent profile info                                     # View configured accounts and AssumeRole mapping
+ic tencent profile switch                                   # Check active auth mode (tccli vs service)
+ic tencent profile switch tccli                             # Switch to personal 'tccli auth login' STS session
+ic tencent profile switch service                           # Switch to service account credentials
+
+# --- CAM Security Audit & Permission Governance ---
+# 1) Credential & Password Hygiene Audit (check)
+ic tencent cam check                                        # Audit sub-accounts & collaborators password/key age
+ic tencent cam check -w                                     # Filter users with 90+ day password/key warnings
+ic tencent cam check -t collaborator                        # Filter external collaborators only
+
+# 2) User Permission, Resource & Condition Inspection (user)
+ic tencent cam user                                         # Inspect users, groups, Direct/Group policies, conditions, roles
+ic tencent cam user -a prod-account -n devops,operator      # Filter by account and user name
+ic tencent cam user --policy CVMFullAccess --resource vpc   # Filter by attached policy or scoped resource
+ic tencent cam user --condition 203.0.113.10 -o tree        # Filter by IP condition and render as a tree
+
+# 3) CAM Policy Inspection (policy)
+ic tencent cam policy                                       # List custom CAM policies and attached entities
+ic tencent cam policy -t all --attached                     # Include attached Tencent QCS preset policies
+ic tencent cam policy --unattached                          # Find unattached custom policies
+ic tencent cam policy -n CustomVpcPolicy -d                 # Display full CAM policy document statements (-d)
+
+# 4) CAM Role Inspection (role)
+ic tencent cam role                                         # List CAM roles, trusted principals, and attached policies
+ic tencent cam role -t user --no-slr                        # Filter user/cross-account roles excluding service-linked roles
+ic tencent cam role --trust cvm,tke --policy FullAccess     # Filter by trusted principal and attached policy
+ic tencent cam role -o tree                                 # Render role trust and policy hierarchy as a tree
+
+# --- CVM, Lighthouse & Containers ---
+ic tencent cvm info                                         # List CVM instances across accounts and regions
+ic tencent cvm info -a prod-account -n "api,batch"          # Multi-pattern instance name search
+ic tencent cvm info -c ">=2026-01-01"                       # Filter instances created on or after 2026-01-01
+ic tencent cvm info -p                                      # Spreadsheet copy-paste CSV output
+ic tencent cvm desc -l                                      # Discover CVM schema keys
+ic tencent cvm desc -k InstanceId,InstanceState,PrivateIpAddresses.0
+
+ic tencent lighthouse info                                  # List Lighthouse lightweight servers
+ic tencent lighthouse info -p                               # Spreadsheet copy-paste CSV output
+ic tencent lighthouse firewall                              # Inspect Lighthouse instance firewall rules
+ic tencent lighthouse firewall -o tree                      # Render Lighthouse firewall rules in tree view
+ic tencent lighthouse firewall --port 22 --action ACCEPT    # Filter firewall rules by port and action
+
+ic tencent tke info                                         # Inspect TKE Kubernetes clusters and nodes
+ic tencent cbs info                                         # Inspect Cloud Block Storage (CBS) volumes
+
+# --- Networking & Cloud Load Balancer (CLB) ---
+ic tencent clb info                                         # Inspect CLBs, listeners, domain rules, and target health
+ic tencent clb traffic                                      # Query 7-day CLB bandwidth (Avg/Max Mbps) and total traffic
+ic tencent clb traffic -d 30                                # Query 30-day CLB bandwidth and traffic statistics
+ic tencent sg info -o tree                                  # Render Security Group ingress/egress rules in tree view
+ic tencent vpc info                                         # Inspect VPCs and Subnets
+ic tencent nat info                                         # Inspect NAT Gateways
+```
+
+---
+
+### 3. GCP Command Examples
+
+```bash
+# Compute Engine VM instances
+ic gcp compute info                                         # Standard VM inventory across projects/zones
+ic gcp compute info -a sample-project-01 -v                 # Verbose 15-column output
+ic gcp compute desc -l                                      # List queryable VM schema keys
+ic gcp compute desc -k status,machine_type,internal_ip      # Extract specific VM attributes
+
+# Load Balancing (ALB / NLB)
+ic gcp lb info                                              # Inspect forwarding rules, proxies, and backend services
+ic gcp lb desc -l                                           # List queryable LB schema keys
+ic gcp lb desc -k type,ip_address,backend_services.0.name   # Extract specific LB attributes
+
+# Containers, Serverless, Databases & Networking
+ic gcp gke info                                             # GKE clusters and node pools
+ic gcp run info                                             # Cloud Run services and revisions
+ic gcp functions info                                       # Cloud Functions inventory
+ic gcp sql info                                             # Cloud SQL instances
+ic gcp storage info                                         # Cloud Storage buckets
+ic gcp vpc info                                             # VPC networks and subnets
+ic gcp firewall info                                        # VPC firewall ingress/egress rules
+ic gcp dns info                                             # Cloud DNS managed zones
+ic gcp project info                                         # Folder and project hierarchy tree
+ic gcp billing info                                         # Monthly billing breakdown by service
+```
+
+---
+
+### 4. OCI, CloudFlare, SSH & Security Command Examples
+
+```bash
+# Oracle Cloud Infrastructure (OCI)
+ic oci vm info                                              # Compute VM instances
+ic oci aci info                                             # Autonomous Container Instances
+ic oci vcn info                                             # Virtual Cloud Networks and Subnets
+ic oci lb info                                              # Load Balancers
+ic oci nsg info                                             # Network Security Groups
+ic oci volume info                                          # Block Volumes
+ic oci obj info                                             # Object Storage buckets
+ic oci compartment                                          # Compartment hierarchy tree
+ic oci policy info                                          # IAM Policies
+ic oci cost usage                                           # Cost and billing usage report
+
+# CloudFlare (supports both 'ic cf' and 'ic cloudflare')
+ic cf zone info                                             # List CloudFlare zones
+ic cf dns info                                              # Inspect DNS records across zones
+
+# SSH Server Management
+ic ssh info                                                 # Auto-discover and verify SSH servers from ~/.ssh/config
+
+# Built-in Security Scanner & Git Hooks
+ic security scan                                            # Scan workspace for hardcoded secrets or private keys
+ic security install-hooks                                   # Install pre-commit secret scanning hooks
+```
+
+---
+
+## Testing & Verification
+
+The test suite is organized into Core Unit Tests (`tests/unit/`) and Platform Test Suites (`tests/platforms/<platform>/`) with automatic CI platform discovery:
+
+```bash
+# Run the full test suite (Core + All Platforms)
+PYTHONPATH=src:. pytest -q
+
+# Run Core Unit Tests only
+PYTHONPATH=src:. pytest tests/unit
+
+# Run tests for a specific cloud platform
+PYTHONPATH=src:. pytest tests/platforms/aws
+PYTHONPATH=src:. pytest tests/platforms/tencent
+PYTHONPATH=src:. pytest tests/platforms/gcp
+PYTHONPATH=src:. pytest tests/platforms/oci
+PYTHONPATH=src:. pytest tests/platforms/cloudflare
+PYTHONPATH=src:. pytest tests/platforms/ssh
+
+# Build wheel and run isolated clean-virtualenv smoke test
+bash scripts/ci-smoke-test.sh
+```
+
+---
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.