How wakeful/veil works
Project type and purpose
• This is a standalone command‐line tool (written in Go) that queries AWS IAM to expose trust relationships (who can assume which roles) and emits a JSON report.
• There is no frontend or persistent datastore—its sole job is to call AWS APIs, process the results, and print JSON to stdout.
File structure
• Top‐level Go module (go.mod, go.sum) with source files:
• main.go → CLI entrypoint and flag parsing
• types.go → domain types for principals, roles, trust graphs
• utils.go → core logic: AWS SDK calls + data transformation
• utils_test.go → unit tests for utility functions
• tools/ directory → secondary Go module, likely for build tools or optional subcommands
• CI/CD and release artifacts:
• .github/workflows/release.yml → GitHub Actions for build/test/release
• goreleaser.yml → automated binary packaging
• golangci.yaml, .pre-commit-config.yaml → linting & pre-commit checks
README for additional insights
• Uses the AWS Go SDK under the hood
• Outputs a map from “principal” → list of “roles they can assume”
• Designed for quick auditing via CLI, pipelines, or piping to jq
Main components
a. CLI Layer
• Flag parser (region, verbose, version)
• Invocation by user or CI/CD
b. AWS Communication Layer
• AWS SDK IAM client
• Authentication/credentials resolution (env vars, static creds, EC2/assume-role)
• API calls: ListRoles, ListPolicies, GetRolePolicy, etc.
c. Data Processing Layer
• Graph builder that maps “who trusts whom”
• Filtering/aggregation logic
d. Output Layer
• JSON marshalling
• Stdout writer, exit codes
e. DevOps/CI Pipeline (external)
• GitHub Actions (lint, test, release)
• GoReleaser produces cross-platform binaries
• Optional tools/ subproject
Relationships and data flow
• User invokes veil → CLI Layer parses flags → AWS SDK client fetches IAM data → passes raw data to the Data Processing Layer → builds trust graph → JSON Formatter serializes graph → CLI writes to stdout.
• CI/CD pipeline invokes tests & linters against the same codebase and triggers GoReleaser on tagged commits.
Architectural patterns and design principles
• Single‐binary micro‐CLI: minimal external dependencies
• Clear separation of concerns:
• main.go only handles I/O and flag parsing
• utils.go + types.go encapsulate business logic and domain models
• utils_test.go ensures core logic correctness
• Infrastructure as Code for releases (Goreleaser) and CI (GitHub Actions)
Relevant technologies and frameworks
• Go (modules, standard library)
• AWS Go SDK (IAM service client)
• GoReleaser for releases
• golangci-lint, pre-commit hooks
• Use clear labels on each component (e.g., “Flag Parser”, “IAM Client”, “Graph Builder”)
• Input flow (User → CLI)
• API calls (CLI → AWS IAM)
• Data flow (IAM → Processor → JSON Output)
• Blue rectangles for runtime modules
• Orange documents for artifacts (JSON output)
Final advice
• Be exhaustive in naming each functionally distinct piece: entrypoint, credential resolution, API interaction, processing, output.
• Dev tooling (linters, tests) as part of the architecture—this shows how quality is enforced.