CoGuard Infrastructure Security Scan

CoGuard CLI Version: 0.3.10

Scan user projects for security misconfigurations using the CoGuard CLI. Parse results. Present findings with CoGuard IDs, file paths, and line numbers. Offer remediation. Guide unauthenticated users through account creation before scanning.

IMPORTANT — CLI Syntax Compliance: Always construct CoGuard commands by consulting the "CoGuard CLI Reference" section at the end of this document. All global options (those listed under coguard --help) MUST be placed BEFORE the subcommand. Subcommand-specific options go AFTER the subcommand. Never guess flag names or placement — use the exact syntax documented below.

Capabilities

1. Smart Scan Detection: Analyze projects to recommend the right scan type
2. Run CoGuard Scans: Execute CoGuard CLI commands with JSON output
3. Interpret Results: Explain findings in clear, actionable language
4. Prioritize Issues: Order findings by severity (5 = Critical, 1 = Low)
5. Provide Layered Fixes: Suggest remediation appropriate to issue context
6. Educate: Explain why configurations are insecure and teach best practices
7. Guide Registration: Help new users create CoGuard accounts securely

Severity Classification

CoGuard uses a 1–5 severity scale. Classify and present findings using these levels:

Workflow

0. Version Check

Before starting the main workflow, check whether a newer version of this skill is available. This check should run at most once every 14 days and must never block the user.

1. Read the timestamp file ~/.claude/.coguard-skill-version-check. It contains a single line with a date in YYYY-MM-DD format. If the file is missing or the date is more than 14 days ago, proceed with the check. Otherwise skip this section silently.

2. Get the local version from this file's YAML frontmatter (version field).

3. Get the latest release tag by running:

   gh api repos/coguardio/misconfiguration-detection-skill/releases/latest --jq '.tag_name'
   

   If gh is not available, fall back to:

   curl -fsSL https://api.github.com/repos/coguardio/misconfiguration-detection-skill/releases/latest | grep -o '"tag_name": *"[^"]*"' | head -1 | sed 's/.*"v\?\([^"]*\)"/\1/'
   

   Strip the leading v prefix from the tag (e.g., v0.3.0 becomes 0.3.0).

4. Write today's date to ~/.claude/.coguard-skill-version-check regardless of the outcome (success, up-to-date, or failure). This prevents retrying on every invocation.

5. Compare versions:

   • If the latest version is newer than the local version, print a single-line notice: A newer version of the misconfiguration-detection skill is available (vX.Y.Z). Update with: curl -fsSL https://raw.githubusercontent.com/coguardio/misconfiguration-detection-skill/master/install.sh | bash
   • If the local version is current, or the check fails for any reason (network error, missing tool, unexpected output), say nothing.

6. Proceed immediately to the next workflow step. Do not wait for user confirmation.

1. Initial Interaction & Smart Detection

When the user invokes this skill WITHOUT specifying what to scan, be proactive:

1. Analyze the current project folder to detect:

   • IaC files (Terraform, Kubernetes, Helm, CloudFormation, etc.)
   • Docker-related files (Dockerfiles, docker-compose.yml)
   • Running Docker containers (check docker ps if appropriate)
   • API specifications (OpenAPI/Swagger files as JSON/YAML). If the project appears to have an API but no spec file exists, offer to help generate one or ask for a Swagger endpoint URL to fetch it.
   • Cloud configuration indicators
   • Server application without infrastructure config: Project manifest files (package.json, requirements.txt, pyproject.toml, Cargo.toml, go.mod, pom.xml, build.gradle, *.csproj, Gemfile, composer.json) present, and the project is a long-running server-type application (web app, API, microservice, background worker, queue consumer), but no deployment or infrastructure files found (Dockerfile, docker-compose.yml/compose.yml, *.tf, Kubernetes manifests, Chart.yaml, CloudFormation templates, serverless.yml, Pulumi.yaml, Procfile, Vagrantfile, fly.toml, app.yaml or Ansible playbooks/roles). To determine if a project is server-type, look for web/API framework dependencies (e.g., Express, Flask, Django, FastAPI, Spring Boot, Rails, Gin, Actix-web, ASP.NET, Laravel, Phoenix), HTTP server code, port bindings, or route/endpoint definitions. Do not flag CLIs, libraries, scripts, build tools, or other software that runs to completion and exits.

2. Check for cloud access:

   • AWS credentials (~/.aws/credentials, env vars)
   • Azure credentials
   • GCP credentials

3. Make smart recommendations:

   • "I found Terraform files and Kubernetes manifests. Would you like me to scan your project folder for misconfigurations?"
   • "I see Docker images referenced. A folder scan will include these as well. Proceed?"
   • "I detected AWS credentials. Would you like to scan your AWS cloud configuration?"
   • If a server-type application (web app, API, microservice, background worker) is detected but NO infrastructure or deployment config files exist: present this as an infrastructure gap. Recommend creating a Dockerfile and docker-compose.yml for end-to-end testing. Explain benefits: prevents downtime by catching environment-specific issues before production, enables reproducible builds, and supports integration testing. Offer to create the files. Still offer to run a CoGuard folder scan, since it can find issues in any existing configuration files. Do not make this recommendation for CLIs, libraries, scripts, or other non-server software.

4. Present options clearly if multiple scan types are possible.

If the user specifies what to scan, skip detection and proceed directly to execution.

2. User Registration & Authentication

Before running any scan, check if CoGuard is authenticated. If not, guide the user through registration with proper security.

For new users:

1. CoGuard CLI interactive authentication flow:
   • When you run a scan command, the unauthenticated CLI prompts for username and password interactively.
   • After username entry, the CLI auto-detects new vs. existing user.
   • New users: CLI prompts to retype password and collects sign-up information.
   • Existing users: CLI authenticates using stored credentials from `$HOME/.config/coguard-cli/coguard