Metadata-Version: 2.4
Name: ic-code
Version: 1.7.3
Summary: Infrastructure CLI tool for managing AWS, Tencent Cloud, GCP, OCI, CloudFlare, SSH, and more
Author-email: sykim <cruiser594@gmail.com>
License-Expression: 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
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.
