docs: update project positioning for authorized cloud security validation

Author: 404tk

README.md

@@ -1,14 +1,65 @@
 # CloudToolKit
 
-Interactive multi-cloud security assessment framework.
+CloudToolKit is an adversary simulation and validation toolkit for assessing the effectiveness of CSPM, CNAPP, and related cloud detection and investigation platforms in authorized environments.
+
+## Overview
+
+CloudToolKit helps defenders reproduce realistic cloud security scenarios in owned labs, approved internal subscriptions, and explicitly authorized customer environments. It is designed for defensive validation through cloud asset inventory, identity and privilege abuse checks, suspicious resource activity review, and authorized instance command checks that generate realistic telemetry for detection and investigation testing.
+
+## Why This Project Exists
+
+Enterprise cloud security teams need repeatable validation workflows that answer practical questions:
+
+- Can the platform detect suspicious cloud behavior in an authorized test environment?
+- Does the telemetry preserve enough context for investigation?
+- Can analysts correlate identity activity, resource changes, and control failures?
+- Where are the visibility gaps across CSPM, CNAPP, and related cloud security tooling?
+
+## What It Validates
+
+CloudToolKit is intended to help defenders verify:
+
+- platform coverage across CSPM, CNAPP, and related cloud detection and investigation tooling
+- telemetry quality for triage, investigation, and root-cause analysis
+- investigation readiness across identity, compute, storage, and database activity
+- control visibility gaps that require tuning, additional telemetry, or compensating detections
 
 ## Features
 
-- **Multi-Cloud Support** - Alibaba, Tencent, Huawei, AWS, Azure, GCP, Volcengine, JDCloud
-- **Asset Enumeration** - Hosts, databases, storage buckets, domains, IAM users
-- **Security Testing** - Backdoor user creation, command execution, bucket dumping
-- **Interactive CLI** - Tab completion, session management, credential caching
-- **Lightweight Provider Clients** - AWS/Azure/Tencent/Huawei/Alibaba are being gradually decoupled from heavy official SDK paths
+- **Multi-Cloud Coverage** - Alibaba, Tencent, Huawei, AWS, Azure, GCP, Volcengine, and JDCloud
+- **Cloud Asset Inventory** - Hosts, databases, storage buckets, domains, IAM users, and related cloud resources
+- **Defender-Side Validation Payloads** - `iam-user-check`, `bucket-check`, `instance-cmd-check`, `event-check`, and `rds-account-check`
+- **Interactive CLI** - Tab completion, session management, and credential caching
+- **Lightweight Provider Clients** - AWS, Azure, Tencent, Huawei, and Alibaba integrations are being gradually decoupled from heavy official SDK paths
+
+## Use Cases
+
+- storage exposure checks in authorized environments
+- IAM lifecycle checks for identity telemetry and alert validation
+- instance execution telemetry checks for detection and investigation workflows
+- RDS account validation for database visibility and control verification
+- cross-signal investigation testing across identity, compute, storage, and database activity
+
+## Example Validation Workflows
+
+- Use `cloudlist` in an authorized environment to verify whether a CSPM or CNAPP accurately discovers compute, storage, identity, database, and DNS resources.
+- Use `iam-user-check` to create or remove a test IAM user and validate identity telemetry, alerting, and persistence detection coverage.
+- Use `instance-cmd-check` to generate telemetry for command execution, process correlation, and investigation workflows on a test instance.
+- Use `event-check` to review cloud security events and suspicious resource operations for investigation context, enrichment quality, and timeline reconstruction.
+- Use `rds-account-check` to provision read-only RDS access in an authorized environment to validate database visibility, control coverage, and investigation readiness.
+
+## Supported Capabilities
+
+| Provider | Inventory Coverage | Validation Payloads |
+|:--------:|:-----------:|:--------------------:|
+| Alibaba Cloud | ECS, OSS, RAM, RDS, DNS, SLS, SMS | iam-user-check, bucket-check, instance-cmd-check, event-check, rds-account-check |
+| Tencent Cloud | CVM, Lighthouse, COS, CAM, CDB, DNSPod | iam-user-check, bucket-check, instance-cmd-check |
+| Huawei Cloud | ECS, OBS, IAM, RDS | iam-user-check, bucket-check |
+| AWS | EC2, S3, IAM | iam-user-check, bucket-check |
+| Azure | Virtual Machines, Blob Storage | - |
+| GCP | Compute Engine, Cloud DNS, IAM | - |
+| Volcengine | ECS, IAM | - |
+| JDCloud | VM, IAM, OSS | - |
 
 ## Quick Start
 
@@ -20,18 +71,18 @@ go build --ldflags "-s -w" -trimpath -o ctk cmd/main.go
 ./ctk
 ```
 
-## Supported Capabilities
+## Responsible Use
 
-| Provider | Enumeration | Security Testing |
-|:--------:|:-----------:|:----------------:|
-| Alibaba Cloud | ECS, OSS, RAM, RDS, DNS, SLS, SMS | backdoor-user, bucket-dump, exec-command, event-dump, database-account |
-| Tencent Cloud | CVM, Lighthouse, COS, CAM, CDB, DNSPod | backdoor-user, bucket-dump, exec-command |
-| Huawei Cloud | ECS, OBS, IAM, RDS | backdoor-user, bucket-dump |
-| AWS | EC2, S3, IAM | backdoor-user, bucket-dump |
-| Azure | Virtual Machines, Blob Storage | - |
-| GCP | Compute Engine, Cloud DNS, IAM | - |
-| Volcengine | ECS, IAM | - |
-| JDCloud | VM, IAM, OSS | - |
+CloudToolKit is intended only for owned environments, lab environments, approved internal subscriptions, and explicitly authorized customer environments. It is designed to help defenders verify detection coverage, telemetry quality, investigation workflows, and control effectiveness. It is not intended for unauthorized access, third-party abuse, or covert real-world intrusion activity.
+
+## Non-Goals
+
+CloudToolKit is not positioned as:
+
+- an unauthorized offensive toolkit
+- a stealth or bypass framework
+- a weaponized intrusion utility
+- guidance for abuse against third-party environments
 
 ## Documentation
 
@@ -41,4 +92,3 @@ See [Wiki](https://github.com/404tk/cloudtoolkit/wiki) for detailed usage.
 
 - [c-bata/go-prompt](https://github.com/c-bata/go-prompt)
 - [projectdiscovery/cloudlist](https://github.com/projectdiscovery/cloudlist)
-- [rapid7/metasploit-framework](https://github.com/rapid7/metasploit-framework)

pkg/providers/alibaba/rds/accounts.go

@@ -11,7 +11,7 @@ import (
 )
 
 func (d *Driver) CreateAccount(instanceID, dbName string) bool {
-	accountName, accountPassword, ok := parseDBAccount()
+	accountName, accountPassword, ok := parseRDSAccount()
 	if !ok {
 		return false
 	}
@@ -34,7 +34,7 @@ func (d *Driver) CreateAccount(instanceID, dbName string) bool {
 }
 
 func (d *Driver) DeleteAccount(instanceID string) {
-	accountName, _, ok := parseDBAccount()
+	accountName, _, ok := parseRDSAccount()
 	if !ok {
 		return
 	}
@@ -53,10 +53,10 @@ func grantAccountPrivilege(ctx context.Context, client *api.Client, region, inst
 	return err
 }
 
-func parseDBAccount() (string, string, bool) {
-	accountName, accountPassword, ok := strings.Cut(utils.DBAccount, ":")
+func parseRDSAccount() (string, string, bool) {
+	accountName, accountPassword, ok := strings.Cut(utils.RDSAccount, ":")
 	if !ok || strings.TrimSpace(accountName) == "" || strings.TrimSpace(accountPassword) == "" {
-		logger.Error("DB account metadata is invalid. expected username:password")
+		logger.Error("RDS account metadata is invalid. expected username:password")
 		return "", "", false
 	}
 	return accountName, accountPassword, true

pkg/providers/alibaba/rds/rds_test.go

@@ -147,10 +147,10 @@ func TestCreateAccountCreatesReadonlyUserAndGrantsPrivilege(t *testing.T) {
 		logger.SetOutput(nil)
 	})
 
-	originalAccount := utils.DBAccount
-	utils.DBAccount = "readonly:Secret!1"
+	originalAccount := utils.RDSAccount
+	utils.RDSAccount = "readonly:Secret!1"
 	t.Cleanup(func() {
-		utils.DBAccount = originalAccount
+		utils.RDSAccount = originalAccount
 	})
 
 	var actions []string
@@ -207,10 +207,10 @@ func TestDeleteAccountUsesConfiguredCredential(t *testing.T) {
 		logger.SetOutput(nil)
 	})
 
-	originalAccount := utils.DBAccount
-	utils.DBAccount = "readonly:Secret!1"
+	originalAccount := utils.RDSAccount
+	utils.RDSAccount = "readonly:Secret!1"
 	t.Cleanup(func() {
-		utils.DBAccount = originalAccount
+		utils.RDSAccount = originalAccount
 	})
 
 	var actions []string

pkg/schema/schema.go

@@ -14,45 +14,45 @@ type Provider interface {
 	Name() string
 }
 
-// Enumerator powers the cloudlist payload.
+// Enumerator powers the asset-inventory (`cloudlist`) payload.
 type Enumerator interface {
 	Provider
 	Resources(ctx context.Context) (Resources, error)
 }
 
-// IAMManager powers the backdoor-user payload.
+// IAMManager powers the iam-user-check payload.
 type IAMManager interface {
 	Provider
 	UserManagement(action, username, password string)
 }
 
-// BucketManager powers the bucket-dump payload.
+// BucketManager powers the bucket-check payload.
 type BucketManager interface {
 	Provider
 	BucketDump(ctx context.Context, action, bucketName string)
 }
 
-// EventReader powers the event-dump payload.
+// EventReader powers the event-check payload.
 type EventReader interface {
 	Provider
 	EventDump(action, args string)
 }
 
-// VMExecutor powers the exec-command / shell payloads.
+// VMExecutor powers the instance-cmd-check / shell payloads.
 type VMExecutor interface {
 	Provider
 	ExecuteCloudVMCommand(instanceID, cmd string)
 }
 
-// DBManager powers the database-account payload.
+// DBManager powers the rds-account-check payload.
 type DBManager interface {
 	Provider
 	DBManagement(action, instanceID string)
 }
 
 // Asset is any cloud resource that can be enumerated and rendered. New asset
 // types (FaaS, K8s clusters, container registries, etc.) only need to
-// implement AssetType() to flow through the existing cloudlist pipeline.
+// implement AssetType() to flow through the existing asset-inventory pipeline.
 type Asset interface {
 	AssetType() string
 }
@@ -111,8 +111,8 @@ func (r Resources) Err() error {
 }
 
 // Grouped returns assets partitioned by AssetType() while preserving insertion
-// order within each bucket. Used by the cloudlist printer so each asset type
-// renders as its own table.
+// order within each bucket. Used by the asset-inventory printer so each asset
+// type renders as its own table.
 func (r *Resources) Grouped() map[string][]Asset {
 	out := make(map[string][]Asset)
 	for _, a := range r.Assets {

runner/console/completer.go

@@ -11,18 +11,18 @@ import (
 
 var core = []prompt.Suggest{
 	{Text: "help", Description: "help menu"},
-	{Text: "use", Description: "use module"},
+	{Text: "use", Description: "use provider"},
 	{Text: "sessions", Description: "list cache credential"},
 	{Text: "note", Description: "add remarks to the session"},
 	{Text: "clear", Description: "clear screen"},
 	{Text: "exit", Description: "exit console"},
 }
 
 var action = []prompt.Suggest{
-	{Text: "show", Description: "show options"},
-	{Text: "set", Description: "set option"},
-	{Text: "run", Description: "run job"},
-	{Text: "shell", Description: "run commands"},
+	{Text: "show", Description: "show options or payloads"},
+	{Text: "set", Description: "set option or parameter"},
+	{Text: "run", Description: "run selected payload"},
+	{Text: "shell", Description: "open instance-cmd-check session"},
 }
 
 var modules = func() (m []prompt.Suggest) {
@@ -34,10 +34,10 @@ var modules = func() (m []prompt.Suggest) {
 
 var optionsDesc = map[string]string{
 	// utils.Provider:              "Vendor Name",
-	utils.Payload:               "Module Name (Default: cloudlist)",
+	utils.Payload:               "Validation payload (Default: cloudlist)",
 	utils.AccessKey:             "Key ID",
 	utils.SecretKey:             "Secret",
-	utils.SecurityToken:         "Securit Token (Optional)",
+	utils.SecurityToken:         "Security Token (Optional)",
 	utils.Region:                "Region (Default: all)",
 	utils.Version:               "International or custom edition (Optional)",
 	utils.AzureClientId:         "Key ID",
@@ -95,8 +95,8 @@ func actionCompleter(d prompt.Document) []prompt.Suggest {
 		}
 		if len(args) == 3 && args[1] == utils.Payload {
 			getPayloads := func() (p []prompt.Suggest) {
-				for k, v := range payloads.Payloads {
-					p = append(p, prompt.Suggest{Text: k, Description: v.Desc()})
+				for _, entry := range payloads.Visible() {
+					p = append(p, prompt.Suggest{Text: entry.Name, Description: entry.Payload.Desc()})
 				}
 				return
 			}()

runner/console/executor.go

@@ -88,36 +88,36 @@ func Executor(s string) {
 }
 
 // confirmIfSensitive prompts the user before dispatching payloads that mutate
-// cloud state. Read-only payloads (cloudlist, bucket-dump, event-dump.dump)
-// bypass the prompt. exec-command is intentionally skipped here so the shell
-// REPL, which enters a single confirmation at session start, does not prompt
-// on every keystroke.
+// cloud state. Read-only payloads (cloud asset inventory via `cloudlist`,
+// bucket-check, and event-check in dump mode) bypass the prompt.
+// instance-cmd-check is skipped here so the shell REPL, which enters a single
+// confirmation at session start, does not prompt on every keystroke.
 func confirmIfSensitive(config map[string]string) bool {
-	payload := config[utils.Payload]
+	payload := payloads.ResolveName(config[utils.Payload])
 	metadata := config[utils.Metadata]
 	parts := argparse.Split(metadata)
 	provider := config[utils.Provider]
 
 	switch payload {
-	case "backdoor-user":
+	case "iam-user-check":
 		if len(parts) < 2 {
 			return true
 		}
-		return confirm.Ask("backdoor-user."+parts[0], provider, parts[1])
-	case "database-account":
+		return confirm.Ask("iam-user-check."+parts[0], provider, parts[1])
+	case "rds-account-check":
 		if len(parts) < 2 {
 			return true
 		}
-		return confirm.Ask("database-account."+parts[0], provider, parts[1])
-	case "event-dump":
+		return confirm.Ask("rds-account-check."+parts[0], provider, parts[1])
+	case "event-check":
 		if len(parts) < 1 || parts[0] != "whitelist" {
 			return true
 		}
-		target := ""
+		resource := ""
 		if len(parts) >= 2 {
-			target = parts[1]
+			resource = parts[1]
 		}
-		return confirm.Ask("event-dump.whitelist", provider, target)
+		return confirm.Ask("event-check.whitelist", provider, resource)
 	}
 	return true
 }
@@ -141,10 +141,10 @@ func show(args []string) {
 			}
 		}
 	case "payloads":
-		fmt.Printf("\n%-10s\t%-60s\n", "Payload", "Details")
-		fmt.Printf("%-10s\t%-60s\n", "-------", "-------")
-		for k, v := range payloads.Payloads {
-			fmt.Printf("%-15s\t%-60s\n", k, v.Desc())
+		fmt.Printf("\n%-24s\t%-60s\n", "Payload", "Details")
+		fmt.Printf("%-24s\t%-60s\n", "-------", "-------")
+		for _, entry := range payloads.Visible() {
+			fmt.Printf("%-24s\t%-60s\n", entry.Name, entry.Payload.Desc())
 		}
 	}
 }
@@ -153,28 +153,34 @@ func set(args []string) {
 	if len(args) < 2 {
 		return
 	}
-	if _, ok := config[args[0]]; ok {
-		if args[0] != utils.Provider {
-			config[args[0]] = args[1]
-			fmt.Printf("%s => %s\n", args[0], args[1])
+	key := args[0]
+	if _, ok := config[key]; ok {
+		if key != utils.Provider {
+			value := args[1]
+			if key == utils.Payload {
+				value = payloads.ResolveName(value)
+			}
+			config[key] = value
+			fmt.Printf("%s => %s\n", key, value)
 		}
 	}
-	if args[0] == utils.Payload {
-		switch args[1] {
-		case "backdoor-user":
-			config[utils.Metadata] = utils.BackdoorUser
-		case "bucket-dump":
-			config[utils.Metadata] = utils.BucketDump
-		case "event-dump":
-			config[utils.Metadata] = utils.EventDump
+	if key == utils.Payload {
+		switch config[utils.Payload] {
+		case "iam-user-check":
+			config[utils.Metadata] = utils.IAMUserCheck
+		case "bucket-check":
+			config[utils.Metadata] = utils.BucketCheck
+		case "event-check":
+			config[utils.Metadata] = utils.EventCheck
 		default:
 			config[utils.Metadata] = ""
 		}
 	}
 }
 
 func run(ctx context.Context) {
-	if v, ok := payloads.Payloads[config[utils.Payload]]; ok {
+	if v, name, ok := payloads.Lookup(config[utils.Payload]); ok {
+		config[utils.Payload] = name
 		v.Run(ctx, config)
 	} else {
 		logger.Error("Please type `show payloads` to confirm the required payload.")