Skip to content
Merged
Show file tree
Hide file tree
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -3,4 +3,5 @@ cmd/cloudlist/cloudlist
dist
.env
provider-config.yaml
cloudlist
/cloudlist
/terraform/
185 changes: 185 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,185 @@
# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

**Cloudlist** is a multi-cloud asset discovery tool written in Go that enumerates resources (IPs, DNS names) from various cloud providers using their APIs. It's designed for blue team security operations to maintain centralized cloud asset inventories.

## Build & Development Commands

### Building
```bash
# Build the binary
make build
# or
go build -v -o cloudlist cmd/cloudlist/main.go
```

### Testing
```bash
# Run all tests
make test
# or
go test -v ./...

# Run tests for specific package
go test -v ./pkg/providers/aws/
```

### Linting
```bash
# Run golangci-lint (same as CI)
golangci-lint run --timeout 5m

# Auto-fix issues
golangci-lint run --fix --timeout 5m
```

### Running
```bash
# Basic usage
./cloudlist -pc ~/.config/cloudlist/provider-config.yaml

# Filter by provider
./cloudlist -pc provider-config.yaml -p aws,gcp

# Filter by service
./cloudlist -pc provider-config.yaml -s compute,dns

# Output formats
./cloudlist -pc provider-config.yaml -json > output.json
./cloudlist -pc provider-config.yaml -host # DNS names only
./cloudlist -pc provider-config.yaml -ip # IPs only
```

## Architecture

### Core Components

1. **Provider Interface** (`pkg/schema/schema.go:18-28`)
- All providers implement the `schema.Provider` interface
- Key methods: `Name()`, `ID()`, `Resources(ctx)`, `Services()`
- Returns `*schema.Resources` containing `[]*schema.Resource`

2. **Provider Registration** (`pkg/inventory/inventory.go:92-137`)
- `nameToProvider()` function maps provider names to implementations
- Add new providers here as a case statement

3. **Resource Model** (`pkg/schema/schema.go:142-163`)
- Each resource represents a cloud asset with IP/DNS information
- Fields: `Public`, `Provider`, `Service`, `ID`, `PublicIPv4/v6`, `PrivateIpv4/v6`, `DNSName`, `Metadata`
- Resources are automatically deduplicated by IP/DNS values

4. **Provider Structure Pattern**
- Providers in `pkg/providers/<provider>/`
- Main file: `<provider>.go` with `New()` constructor and `Resources()` implementation
- Service-specific files: `instances.go`, `dns.go`, etc. for complex providers (see AWS)
- Each provider has a `Services` slice listing supported service types

### Provider Implementation Pattern

When implementing providers, follow this structure:

1. **Main provider file** (`<provider>.go`):
- Struct with provider-specific client and configuration
- `New(block schema.OptionBlock)` constructor that validates config
- `Resources(ctx context.Context) (*schema.Resources, error)` that orchestrates resource gathering
- Service-specific helper methods

2. **Service-specific files** (for complex providers):
- AWS example: `instances.go`, `route53.go`, `s3.go`, `eks.go`, etc.
- Each file handles one service type's resource enumeration
- Returns `*schema.Resources` that main `Resources()` method merges

3. **Configuration Parsing**:
- Use `block.GetMetadata(key)` to read config values
- Environment variables supported via `$VAR_NAME` syntax (auto-resolved)
- Return `&schema.ErrNoSuchKey{Name: key}` for missing required config

### Important Patterns

- **Resource Deduplication**: Resources are automatically deduplicated by the `ResourceDeduplicator` in schema
- **Service Filtering**: Users can filter by service via `-s` flag; providers check this in `Services()` method
- **Metadata**: Extended metadata can be added to resources via the `Metadata` map[string]string field
- **Context Handling**: All provider `Resources()` methods receive context for cancellation support

## Adding a New Provider

Required steps:

1. **Create provider directory**: `pkg/providers/<provider-name>/`

2. **Implement provider struct** with these methods:
```go
func New(block schema.OptionBlock) (schema.Provider, error)
func (p *Provider) Name() string
func (p *Provider) ID() string
func (p *Provider) Resources(ctx context.Context) (*schema.Resources, error)
func (p *Provider) Services() []string
```

3. **Register in inventory**: Add case to `nameToProvider()` in `pkg/inventory/inventory.go`

4. **Add to services map**: Add provider and its services to `Providers` map in `pkg/inventory/inventory.go`

5. **Document configuration**: Add provider config documentation to `PROVIDERS.md`

See reference implementations:
- Simple: `pkg/providers/digitalocean/` (single service)
- Complex: `pkg/providers/aws/` (multiple services, sub-files)
- With special auth: `pkg/providers/gcp/` (JSON service account keys)

## Key Files

- `cmd/cloudlist/main.go` - CLI entry point
- `internal/runner/runner.go` - Main enumeration orchestrator
- `internal/runner/options.go` - CLI flag definitions
- `pkg/schema/schema.go` - Core interfaces and data structures
- `pkg/inventory/inventory.go` - Provider registration and factory
- `pkg/providers/*/` - Individual cloud provider implementations

## GCP-Specific Notes

GCP provider supports **two discovery modes**:

1. **Individual Service APIs** (default): Project-level discovery using service-specific APIs
2. **Organization-Level Asset API**: Org-wide discovery when `organization_id` is specified

Key distinction in code:
- Check for `organization_id` in config to determine mode
- Asset API mode uses `cloud.google.com/go/asset` package
- Individual APIs mode uses service-specific clients (compute, dns, etc.)

See `docs/GCP_ASSET_API.md` for detailed implementation guide.

## Testing Guidelines

- Integration tests require cloud provider credentials (usually skipped in CI)
- Unit tests should mock cloud provider clients
- Use table-driven tests for resource parsing logic
- Test error handling for missing/invalid credentials

## GitHub Actions CI

- **lint-test.yml**: Runs `golangci-lint` on Go code changes
- **build-test.yml**: Tests builds on Ubuntu, Windows, macOS with Go 1.22.x
- **release-binary.yml**: Creates releases with GoReleaser

## Common Gotchas

1. **Resource fields**: Either IP or DNS must be populated; empty resources are invalid
2. **Provider IDs**: The `id` field in config is user-defined for filtering, not a cloud resource ID
3. **Service names**: Must match entries in provider's `Services` slice and inventory's `Providers` map
4. **Credential handling**: Use environment variables (`$VAR`) in config rather than hardcoding
5. **Context cancellation**: Always respect context in long-running API calls
6. **Deduplication**: Don't manually deduplicate; use `Resources.Append()` which handles it automatically

## Module Information

- Go version: 1.24+ (see `go.mod`)
- Module path: `github.com/projectdiscovery/cloudlist`
- Key dependencies:
- Provider SDKs: `aws-sdk-go`, `azure-sdk-for-go`, `google.golang.org/api`, etc.
- ProjectDiscovery libs: `goflags`, `gologger`, `utils`
- Concurrency: `github.com/alitto/pond/v2` for worker pools
49 changes: 29 additions & 20 deletions go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,6 @@ toolchain go1.24.2

require (
git.arvancloud.ir/arvancloud/cdn-go-sdk v0.12.1
github.com/Azure/azure-sdk-for-go v68.0.0+incompatible
github.com/Azure/go-autorest/autorest v0.11.28
github.com/Azure/go-autorest/autorest/azure/auth v0.5.12
github.com/Azure/go-autorest/autorest/to v0.4.0 // indirect
github.com/Azure/go-autorest/autorest/validation v0.3.1 // indirect
github.com/aliyun/alibaba-cloud-sdk-go v1.62.560
github.com/aws/aws-sdk-go v1.45.19
github.com/cloudflare/cloudflare-go v0.77.0
Expand Down Expand Up @@ -44,12 +39,6 @@ require (
require (
aead.dev/minisign v0.2.0 // indirect
cloud.google.com/go/compute/metadata v0.7.0 // indirect
github.com/Azure/go-autorest v14.2.0+incompatible // indirect
github.com/Azure/go-autorest/autorest/adal v0.9.18 // indirect
github.com/Azure/go-autorest/autorest/azure/cli v0.4.5 // indirect
github.com/Azure/go-autorest/autorest/date v0.3.0 // indirect
github.com/Azure/go-autorest/logger v0.2.1 // indirect
github.com/Azure/go-autorest/tracing v0.6.0 // indirect
github.com/Masterminds/semver/v3 v3.2.1 // indirect
github.com/VividCortex/ewma v1.2.0 // indirect
github.com/ajg/form v0.0.0-20160802194845-cc2954064ec9 // indirect
Expand Down Expand Up @@ -78,7 +67,6 @@ require (
github.com/go-resty/resty/v2 v2.7.0 // indirect
github.com/goccy/go-json v0.10.2 // indirect
github.com/gogo/protobuf v1.3.2 // indirect
github.com/golang-jwt/jwt/v4 v4.2.0 // indirect
github.com/golang/protobuf v1.5.4 // indirect
github.com/golang/snappy v0.0.4 // indirect
github.com/google/gnostic-models v0.6.8 // indirect
Expand Down Expand Up @@ -151,15 +139,15 @@ require (
github.com/zcalusic/sysinfo v1.0.2 // indirect
go.uber.org/atomic v1.10.0 // indirect
go.uber.org/multierr v1.11.0 // indirect
golang.org/x/crypto v0.39.0 // indirect
golang.org/x/crypto v0.41.0 // indirect
golang.org/x/exp v0.0.0-20250106191152-7588d65b2ba8 // indirect
golang.org/x/mod v0.25.0 // indirect
golang.org/x/net v0.41.0 // indirect
golang.org/x/sys v0.33.0 // indirect
golang.org/x/term v0.32.0 // indirect
golang.org/x/text v0.26.0 // indirect
golang.org/x/mod v0.26.0 // indirect
golang.org/x/net v0.43.0 // indirect
golang.org/x/sys v0.35.0 // indirect
golang.org/x/term v0.34.0 // indirect
golang.org/x/text v0.28.0 // indirect
golang.org/x/time v0.12.0 // indirect
golang.org/x/tools v0.33.0 // indirect
golang.org/x/tools v0.35.0 // indirect
google.golang.org/genproto/googleapis/rpc v0.0.0-20250603155806-513f23925822 // indirect
google.golang.org/grpc v1.73.0 // indirect
google.golang.org/protobuf v1.36.6
Expand All @@ -178,6 +166,22 @@ require (

require (
cloud.google.com/go/asset v1.21.1
github.com/Azure/azure-sdk-for-go/sdk/azcore v1.19.1
github.com/Azure/azure-sdk-for-go/sdk/azidentity v1.13.0
github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/apimanagement/armapimanagement v1.1.1
github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/appcontainers/armappcontainers v1.1.0
github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/appservice/armappservice v1.0.0
github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/cdn/armcdn v1.1.1
github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/compute/armcompute v1.0.0
github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/containerinstance/armcontainerinstance v1.0.0
github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/containerservice/armcontainerservice v1.0.0
github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/dns/armdns v1.2.0
github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/frontdoor/armfrontdoor v1.4.0
github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/network/armnetwork v1.1.0
github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/resources/armresources v1.2.0
github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/resources/armsubscriptions v1.3.0
github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/storage/armstorage v1.8.1
github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/trafficmanager/armtrafficmanager v1.3.0
github.com/alitto/pond/v2 v2.3.2
github.com/dnsimple/dnsimple-go v1.7.0
github.com/projectdiscovery/networkpolicy v0.1.25
Expand All @@ -193,6 +197,8 @@ require (
cloud.google.com/go/longrunning v0.6.7 // indirect
cloud.google.com/go/orgpolicy v1.15.0 // indirect
cloud.google.com/go/osconfig v1.14.6 // indirect
github.com/Azure/azure-sdk-for-go/sdk/internal v1.11.2 // indirect
github.com/AzureAD/microsoft-authentication-library-for-go v1.5.0 // indirect
github.com/Mzack9999/gcache v0.0.0-20230410081825-519e28eab057 // indirect
github.com/Mzack9999/go-http-digest-auth-client v0.6.1-0.20220414142836-eb8883508809 // indirect
github.com/STARRY-S/zip v0.2.1 // indirect
Expand All @@ -209,11 +215,14 @@ require (
github.com/gaissmai/bart v0.25.0 // indirect
github.com/go-logr/stdr v1.2.2 // indirect
github.com/gofrs/flock v0.8.1 // indirect
github.com/golang-jwt/jwt/v5 v5.3.0 // indirect
github.com/google/shlex v0.0.0-20191202100458-e7afc7fbc510 // indirect
github.com/hashicorp/errwrap v1.1.0 // indirect
github.com/hashicorp/golang-lru/v2 v2.0.7 // indirect
github.com/kylelemons/godebug v1.1.0 // indirect
github.com/mholt/archives v0.1.0 // indirect
github.com/nwaples/rardecode/v2 v2.0.0-beta.4.0.20241112120701-034e449c6e78 // indirect
github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c // indirect
github.com/projectdiscovery/fastdialer v0.4.11 // indirect
github.com/projectdiscovery/hmap v0.0.95 // indirect
github.com/projectdiscovery/retryabledns v1.0.107 // indirect
Expand All @@ -238,7 +247,7 @@ require (
go.opentelemetry.io/otel/metric v1.36.0 // indirect
go.opentelemetry.io/otel/trace v1.36.0 // indirect
go4.org v0.0.0-20230225012048-214862532bf5 // indirect
golang.org/x/sync v0.15.0 // indirect
golang.org/x/sync v0.16.0 // indirect
google.golang.org/genproto v0.0.0-20250505200425-f936aa4a68b2 // indirect
google.golang.org/genproto/googleapis/api v0.0.0-20250505200425-f936aa4a68b2 // indirect
)
Loading
Loading