stackhawk-api-sherpa

StackHawk API Sherpa

Your guide to navigating the StackHawk API and building great HawkOp commands.

Step 1: Check Freshness

OpenAPI Spec

The spec should be refreshed periodically. Check the file date:

ls -la stackhawk-openapi.json

If older than 30 days, refresh:

curl -o stackhawk-openapi.json https://download.stackhawk.com/openapi/stackhawk-openapi.json

API Reference

Check the Last Updated timestamp in .claude/context/stackhawk-api.md. If the reference is outdated compared to the spec, note which sections need updating.

Step 2: Read the API Reference

Before designing any command:

1. Read .claude/context/stackhawk-api.md
2. Check implementation status - is this endpoint already wrapped?
3. Review the data model relationships diagram
4. Note: Check api-quirks.md for API behaviors that don't match the OpenAPI spec

Step 3: User Value Assessment

Answer these questions before touching code:

• What user problem does this solve?

  • What question does the user want answered?
  • What action do they want to take?

• Who is the user?

  • Developer checking their scans?
  • Security engineer reviewing findings?
  • DevOps automating pipelines?

• How often will this be used?

  • Daily workflow? → Optimize for speed
  • Occasional admin task? → Optimize for clarity

Step 4: Endpoint Selection

Find the Right Endpoint(s)

1. Check the API reference by category
2. Consider: Does one endpoint give all needed data, or do we need multiple?
3. Check if v2 endpoint exists (prefer v2 for better pagination)

Pagination Considerations

• Will the response be large? (100+ items) → Use parallel pagination
• Check if totalCount is available in response
• Max page size is 1000

Rate Limiting

• Which category? Scan (80/sec), User (80/sec), AppList (80/sec), Default (6/sec)
• For bulk operations, consider caching

Step 5: CLI UX Design

Invoke the CLI Designer

For command UX decisions, also invoke /cli-designer to ensure we follow clig.dev principles.

Command Structure Decision Tree

Is this a new resource type or extending existing?

Same resource type? → Extend existing command
  Example: `scan get` extends `scan`

New resource type? → New top-level command
  Example: `finding` as new command

Cross-resource query? → Consider which resource is primary
  Example: "findings for app X" → `app findings` or `finding list --app`?

What operation is this?

Retrieving multiple items → `list` subcommand
  Example: `scan list`, `app list`

Retrieving single item by ID → `get` subcommand
  Example: `scan get <ID>`, `app get <ID>`

Modifying state → Verb subcommand
  Example: `scan start`, `app create`, `config upload`

Naming Conventions

• Commands: lowercase, singular nouns (scan, app, team)
• Subcommands: verbs or list/get (list, get, create, delete)
• Flags: --long-name with -s short form for common ones
• Match existing patterns in hawkop

Standard Flags

--org <ID>        # Organization context
--format <FMT>    # table|json
--limit <N>       # Pagination limit
--debug           # Verbose output
--no-cache        # Bypass cache

Step 6: Implementation Planning

Files to Create/Modify

src/client/models/<resource>.rs   # API model
src/client/mod.rs                 # Trait method
src/client/api/<category>.rs      # Implementation
src/models/display/<resource>.rs  # Display model
src/cli/<command>.rs              # CLI handler
src/cli/mod.rs                    # Command enum
src/main.rs                       # Routing

Implementation Checklist

• API Model - Matches OpenAPI schema?
• Serde attributes - rename_all, aliases for quirks?
• Trait method - Pagination params if needed?
• Error handling - Descriptive error messages?
• Display model - Key fields for table output?
• CLI handler - Follows existing patterns?
• Help text - Clear, actionable descriptions?
• Tests - Unit + integration tests?

Step 7: Verify with Live API

If the OpenAPI spec is unclear:

1. Use hawkop CLI to test (if endpoint implemented)
2. Use StackHawk MCP tools for unimplemented endpoints
3. Document any discrepancies

# Test with hawkop
hawkop <command> --format json | jq .

# Check actual response shape
cargo run -- <command> --format json --debug 2>&1

Step 8: Update Documentation

After implementing:

1. Update API reference - Mark endpoint as ✅ implemented
2. Update CLAUDE.md - Add command to list if new
3. Add tests - Unit and integration

Quick Reference Links

• API Reference: .claude/context/stackhawk-api.md
• API Quirks: api-quirks.md - API behaviors that differ from the OpenAPI spec
• CLI Design Principles: docs/CLI_DESIGN_PRINCIPLES.md
• Implementation Patterns: CLAUDE.md → "Adding New Commands"
• OpenAPI Spec: stackhawk-openapi.json
• Existing Commands: src/cli/ (follow these patterns)

Common Scenarios

"I want to add a list command for X"

1. Check API reference for list endpoint
2. Check if v2 endpoint exists
3. Follow src/cli/app.rs or src/cli/scan.rs as template
4. Add pagination support if large datasets expected

"I want to add a detail/get command"

1. Check API reference for get-by-ID endpoint
2. Consider drill-down (like scan get → alerts → messages)
3. Follow src/cli/scan.rs get() as template

"I want to add an action command (create/delete/start)"

1. Check API reference for POST/DELETE endpoint
2. Design confirmation prompts for destructive actions
3. Consider --yes flag to skip confirmation
4. Return actionable success/error messages

"User wants data that spans multiple endpoints"

1. Identify primary resource
2. Consider if we should make multiple API calls
3. Cache where appropriate
4. Present unified output