If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/j3ssie/osmedeus shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 1w ago
• 4 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Small team — 4 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 96% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live j3ssie/osmedeus repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/j3ssie/osmedeus.

What it runs against: a local clone of j3ssie/osmedeus — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in j3ssie/osmedeus | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 37 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of j3ssie/osmedeus. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/j3ssie/osmedeus.git
#   cd osmedeus
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of j3ssie/osmedeus and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "j3ssie/osmedeus(\\.git)?\\b" \\
  && ok "origin remote is j3ssie/osmedeus" \\
  || miss "origin remote is not j3ssie/osmedeus (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "cmd/osmedeus/main.go" \\
  && ok "cmd/osmedeus/main.go" \\
  || miss "missing critical file: cmd/osmedeus/main.go"
test -f "internal/cloud/provider.go" \\
  && ok "internal/cloud/provider.go" \\
  || miss "missing critical file: internal/cloud/provider.go"
test -f "internal/broker/redis_event.go" \\
  && ok "internal/broker/redis_event.go" \\
  || miss "missing critical file: internal/broker/redis_event.go"
test -f "go.mod" \\
  && ok "go.mod" \\
  || miss "missing critical file: go.mod"
test -f "internal/config/cloud_config.go" \\
  && ok "internal/config/cloud_config.go" \\
  || miss "missing critical file: internal/config/cloud_config.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 37 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~7d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/j3ssie/osmedeus"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Osmedeus is a declarative YAML-based orchestration engine for security automation that executes complex, multi-step scanning workflows across distributed Redis-backed master-worker infrastructure. It combines workflow composition (with hooks, conditional routing, and module exclusion), sandboxed execution (host, Docker, SSH runners), and 80+ security-focused utility functions (nmap integration, SSH execution, TypeScript/Python scripting, SARIF parsing) into a single platform with encrypted credential management and event-driven triggers (cron, file-watch, webhooks). Monorepo structure: cmd/osmedeus/main.go is the CLI entry point; core logic distributed across (likely) internal packages; build/ contains deployment templates (Jinja2 for osm-settings.yaml.j2, systemd service templates); docs/api-swagger/ houses auto-generated REST API definitions; .github/workflows/ defines CI automation. Configuration is YAML-native (osm-settings.production.yaml, osm-settings.postgres-test.yaml) and environment-driven (multiple Dockerfiles for dev, canary, nix-test, toolbox variants).

Security engineers and penetration testers who need to orchestrate complex, repeatable multi-stage security workflows (reconnaissance, vulnerability scanning, exploitation chains) across multiple machines without writing custom orchestration code; also infra-as-code practitioners deploying to DigitalOcean, AWS, GCP, Linode, and Azure.

This is an actively maintained, production-ready project: 4.2MB of Go code, comprehensive Docker and Kubernetes deployment configs (build/docker/, build/infra/), full CI/CD pipelines (nightly-release.yaml, manual-release.yaml), and extensive documentation. The project demonstrates maturity through versioned releases (v5 in go.mod), established patterns for multi-environment testing (postgres-test, nix-test, distributed-e2e compose files), and a stable REST API with Swagger docs.

Primary risk is dependency surface: 50+ third-party Go libraries including cloud SDKs (AWS, DigitalOcean, Pulumi, Azure), JavaScript/TypeScript runtime (goja), and cryptography modules increase attack surface and maintenance burden. Secondary risk: single primary maintainer (j3ssie) pattern visible in repo ownership. No obvious abandoned status, but contribution pattern (if any) should be verified in GitHub metrics. Breaking changes between v4→v5 (per go.mod) suggest potential backwards-incompatibility concerns for existing workflows.

Active development in release automation (.github/workflows/nightly-release.yaml and manual-release.yaml suggest regular releases), distributed system expansion (docker-compose.distributed-e2e.yaml, docker-compose.distributed-test.yaml show recent investment in multi-node testing), and polyglot support (Jinja templating, Nix expressions, Makefile-driven builds suggest tooling infrastructure work). API and SDK maturity (docs/api/README.mdx, Swagger generation) indicates ongoing REST/web UI refinement.

git clone https://github.com/j3ssie/osmedeus.git
cd osmedeus
make build  # or 'make dev' for development setup
./cmd/osmedeus/osmedeus -h  # verify build

Alternatively, use Docker: docker build -f build/docker/Dockerfile -t osmedeus . && docker run osmedeus. Check Makefile for full target list and build/DEPLOYMENT.md for multi-node setups.

Daily commands: Development: make dev or make build (check Makefile for exact targets). Production Docker: docker-compose -f build/docker/docker-compose.production.yaml up. Distributed cluster: docker-compose -f build/docker/docker-compose.distributed-e2e.yaml up. Requires environment setup (see build/docker/.env.example for secrets: API keys, database URLs, Redis endpoints). For local testing with PostgreSQL: docker-compose -f build/docker/docker-compose.postgres-test.yaml up.

• cmd/osmedeus/main.go — Entry point for the Osmedeus orchestration engine; all developers must understand the bootstrap and CLI initialization logic
• internal/cloud/provider.go — Core abstraction for multi-cloud provider support (AWS, GCP, Azure, etc.); essential for understanding distributed execution
• internal/broker/redis_event.go — Event messaging backbone using Redis; critical for inter-component communication and workflow orchestration
• go.mod — Declares all dependencies including AWS SDK v2, Charmbracelet TUI, Pulumi, and Docker SDK; foundational for build and runtime
• internal/config/cloud_config.go — Configuration schema for cloud deployments; required reading for understanding how Osmedeus provisions and manages infrastructure
• internal/client/client.go — HTTP client for API communication; defines request/response patterns used throughout the codebase
• build/docker/docker-compose.yml — Reference compose configuration for local and distributed deployments; shows expected service topology and networking

Add Support for a New Cloud Provider

1. Create a new provider file in internal/cloud/ (e.g., internal/cloud/scaleway.go) implementing the Provider interface defined in internal/cloud/provider.go (internal/cloud/provider.go)
2. Implement required methods: Create(), Destroy(), List(), GetSSHKey(), and health check logic (internal/cloud/scaleway.go)
3. Register the new provider in the factory function in internal/cloud/registry.go (internal/cloud/registry.go)
4. Add provider-specific configuration fields to internal/config/cloud_config.go (internal/config/cloud_config.go)
5. Add example docker-compose and settings files in build/docker/ for testing the new provider (build/docker/docker-compose.yml)

Add a New Workflow Type or Task

1. Define the workflow schema and configuration in internal/config/ (extend cloud_config.go or create workflow_config.go) (internal/config/cloud_config.go)
2. Implement task execution logic that emits events via the Redis broker (internal/broker/redis_event.go)
3. Register the new task type in the task registry (check internal/cloud/registry.go pattern) (internal/cloud/registry.go)
4. Add CLI command in cmd/osmedeus/main.go to trigger the new workflow (cmd/osmedeus/main.go)

Modify Cloud Infrastructure Provisioning

1. Update Pulumi infrastructure definition in internal/cloud/pulumi.go or internal/cloud/pulumi_writer.go (internal/cloud/pulumi.go)
2. Update cloud-init templates in internal/cloud/cloudinit.go for instance initialization (internal/cloud/cloudinit.go)
3. Adjust provider-specific lifecycle code (e.g., internal/cloud/aws.go for AWS-specific tags, security groups) (internal/cloud/aws.go)
4. Update docker-compose files and deployment templates to reflect infrastructure changes (build/docker/docker-compose.production.yaml)

Add Event Logging or Monitoring

1. Extend event schema and publish logic in internal/broker/redis_event.go (internal/broker/redis_event.go)
2. Emit new event types when tasks complete, fail, or reach milestones (internal/cloud/lifecycle.go)
3. Subscribe to events in internal/broker/redis_event.go for aggregation or forwarding (internal/broker/redis_event.go)

• Go 1.26+ — Compiles to stateless binary; enables cross-platform deployment (Linux, macOS, Windows); strong concurrency primitives for distributed orchestration
• Redis — Provides high-throughput event broker for asynchronous task coordination and real-time event streaming across distributed workers
• Multi-cloud SDKs (AWS SDK v2, GCP client, etc.) — Native provider APIs eliminate vendor lock-in; allows runtime selection of infrastructure provider based on configuration
• Pulumi — Infrastructure-as-Code framework for multi-cloud provisioning; enables reproducible infrastructure definitions and version control
• Docker & docker-compose — Standardizes deployment across dev, test, and production environments; enables containerized agent deployment on remote instances
• Charmbracelet TUI libraries (bubbletea, lipgloss, glamour) — Provides rich terminal UI for interactive workflows and real-time status monitoring without external dependencies

• Abstract provider interface vs. single-cloud implementation

  • Why: Supports multiple cloud backends (AWS, GCP, Azure, etc.) with minimal code duplication
  • Consequence: Adds initial development overhead; requires careful interface design to capture provider commonalities; some provider-specific features may not map cleanly to the abstraction

• Synchronous HTTP client + Redis async broker

  • Why: HTTP client handles request/response patterns; Redis handles fire-and-forget event notifications for scalability
  • Consequence: Mixed synchronous and asynchronous patterns require careful error handling and retry logic; developers must understand when to use each approach

• Pulumi for IaC vs. hand-crafted SDK calls

  • Why: Pulumi abstracts infrastructure differences and provides versioning; SDK calls give direct control for complex provisioning
  • Consequence: Dual path adds maintenance burden; Pulumi must be kept in sync with direct SDK usage in provider files

• CLI-first interface with optional REST API

  • Why: CLI enables scriptable automation; REST API supports programmatic access and web UIs
  • Consequence: Two entry points must be maintained; feature parity between CLI and API is critical but easy to miss

• This is not a general-purpose container orchestration platform; it is specifically for security tooling orchestration and vulnerability scanning workflows
• Does not provide built-in authentication/authorization; relies on external identity providers or reverse proxies (implied by 'distributed' architecture docs)
• Not a real-time streaming analytics engine; event broker (Redis) is for coordination, not for complex event processing
• Does not handle persistent storage of artifacts; focuses on orchestration, with storage assumed to be external (S3, GCS, etc.)
• Not Windows-native; assumes Linux/Unix-compatible systems for remote workers and cloud instances

Redis requirement: Distributed mode (docker-compose.distributed-*.yaml files) mandates Redis for queue/state sync; local development may skip this but production deployments cannot. PostgreSQL vs SQLite: Default is SQLite (mattn/go-sqlite3), but production (docker-compose.production.yaml) uses PostgreSQL; schema/migrations must match. LLM API keys: agentic steps require OPENAI_API_KEY, ANTHROPIC_API_KEY, or GOOGLE_GENAI_API_KEY in environment; missing keys cause silent failures. Docker-in-Docker: Docker runner execution likely requires /var/run/docker.sock mounting; SSH runners need pre-configured SSH keys (see build/docker/ssh-test/id_ed25519). Workflow YAML parsing: Uses pongo2 templating + gojq; variable name conflicts or malformed YAML silently fail; validate with lint before deploy. Version pinning: go.mod shows v5 major version; v4 workflows may not be compatible.

• Master-Worker Job Queue (Redis) — Osmedeus distributes workflow execution across workers via Redis; understanding pub/sub, task serialization, and fault recovery is critical for scaling beyond single-machine deployments.
• Declarative YAML Templating (Pongo2 + Jinja2) — Workflows are defined in YAML with variable substitution and conditionals (pongo2); contributors must understand template rendering to add new workflow features or debug template failures.
• Sandboxed Execution Contexts (Host/Docker/SSH) — Osmedeus isolates workflow steps in different execution environments; understanding runner selection, privileged escalation, and output capture is essential for security and debugging.
• Agentic LLM Loops with Tool Calling — Osmedeus embeds Claude/Gemini agents that iteratively call security tools (sub-agent pattern); contributors adding new LLM capabilities must understand structured output, memory management, and agent termination conditions.
• Event-Driven Scheduling (Cron + File-Watch + Webhooks) — Workflows trigger on time-based, file-system, or external events with deduplication and delayed queues; understanding trigger chains and backpressure is needed for robust automation.
• Infrastructure-as-Code Provisioning (Pulumi) — Osmedeus can programmatically spin up cloud VMs (DigitalOcean, AWS, GCP, Azure) via Pulumi; contributors modifying cloud support must understand IaC state management and cross-cloud abstractions.
• JQ-Style JSON Path Querying (gojq) — Workflows extract and transform structured data from tool outputs using JQ expressions (itchyny/gojq); understanding filter composition and array slicing is needed to build reliable data pipelines.

• aquasecurity/trivy — Complementary security scanner (vulnerability detection) often orchestrated via Osmedeus workflows; represents the scanning payload tier.
• nmap/nmap — Referenced in Osmedeus feature set (nmap integration in function library); common reconnaissance target executed by Osmedeus runners.
• gremlin/gremlin-go — Chaos engineering orchestration; shares similar distributed execution and event-driven scheduling patterns for different use case (reliability testing vs security scanning).
• hashicorp/terraform — Infrastructure-as-Code precedent; Osmedeus build/infra uses Pulumi (Terraform alternative) for cloud provisioning, suggesting similar declarative approach.
• elastic/beats — Distributed agent collection framework; Osmedeus master-worker pattern (Redis + distributed runners) parallels Beats' central collection and sidecar architecture.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for Docker Compose configurations

The repo has 7+ docker-compose files (production, test, distributed, postgres-test, etc.) but no visible test suite validating these configurations work correctly. A new contributor could create a GitHub Actions workflow that validates syntax, builds images, and runs basic health checks across different compose scenarios. This prevents configuration drift and deployment failures.

• [ ] Create .github/workflows/docker-compose-validate.yaml to lint all build/docker/docker-compose*.yaml files using docker-compose config
• [ ] Add integration test steps that build docker images from build/docker/Dockerfile* variants
• [ ] Create test matrix for different compose scenarios (production, postgres-test, distributed-test) to verify service health checks pass
• [ ] Document in build/DEPLOYMENT.md which compose file to use for different deployment scenarios

Add API endpoint documentation for missing features in docs/api/

The docs/api/ directory has reference docs, but the file structure and swagger definitions (docs/api-swagger/) suggest undocumented endpoints. The LLM integration (llm.mdx exists) and event-receiver endpoints lack concrete examples. A contributor could audit the swagger.yaml against actual implementations and fill gaps with request/response examples.

• [ ] Parse docs/api-swagger/openapi.yaml and compare endpoints against docs/api/*.mdx files
• [ ] Expand docs/api/event-receiver.mdx with webhook payload examples and retry logic documentation
• [ ] Expand docs/api/llm.mdx with supported models, streaming response handling, and error codes
• [ ] Add docs/api/distributed.mdx with examples of multi-node orchestration and node communication protocols

Implement GitHub Actions workflow for Go dependency security audits and compatibility checks

The project has go 1.26.0 and complex dependencies (pulumi, aws-sdk, gocron) but no visible supply-chain security workflow. A new contributor could add CI that runs nancy/gosec checks and validates go.mod/go.sum integrity on PRs, reducing vulnerability exposure.

• [ ] Create .github/workflows/go-security.yaml that runs 'go mod verify' and 'go mod tidy --check' on every PR
• [ ] Integrate nancy (github.com/sonatype-nexus-community/nancy) to scan go.mod for known vulnerabilities
• [ ] Integrate gosec to scan cmd/ and pkg/ directories for security anti-patterns
• [ ] Add go vet and staticcheck runs with failure on warnings to catch quality issues early

• Add integration tests for the 80+ utility functions listed in README: currently no dedicated test file visible in top 60 entries; pick 5 functions (e.g., nmap wrapper, tmux session, SARIF parser) and write table-driven Go tests under internal/func or pkg/func to improve coverage.
• Document the workflow YAML schema with JSON Schema artifact: docs/api/ has README.mdx but no formal schema definition; generate a JSON Schema from the pongo2 template parser (osm-settings.yaml.j2) to enable IDE validation and OpenAPI tooling, saving new users hours of YAML debugging.
• Add telemetry/observability examples to docs/api/README.mdx: project has Prometheus (prometheus/client_golang) and Telegram support but no worked example of scraping metrics or setting up alerting; add 2-3 runnable examples (Prometheus query, Grafana dashboard config, Telegram webhook).

• High · Outdated Go Version — go.mod. The project specifies 'go 1.26.0' which appears to be a future/non-existent version. This could indicate a configuration error or use of development builds, which may contain unpatched vulnerabilities. Fix: Use a stable, officially released Go version (e.g., 1.22, 1.23). Verify the build configuration and update to the latest stable release.
• High · Hardcoded SSH Test Keys — build/docker/ssh-test/id_ed25519. SSH private key file 'id_ed25519' is present in the repository at 'build/docker/ssh-test/'. Even though it's in a test directory, storing private keys in version control is a critical security risk. Fix: Remove the private key from the repository immediately. Add it to .gitignore. Use temporary/ephemeral keys for testing or generate them at runtime. Rotate any exposed keys.
• High · Incomplete Dependency Declaration — go.mod. The go.mod file appears truncated - 'github.com/pulumi' dependency is incomplete. This prevents proper dependency resolution and may hide vulnerable packages. Fix: Complete the go.mod file with all dependencies. Run 'go mod tidy' to ensure all dependencies are properly declared and versions are pinned.
• Medium · Environment Configuration Files — build/docker/.env.example. The presence of '.env.example' and configuration templates suggests environment variables are used for sensitive data. If actual .env files are committed, secrets could be exposed. Fix: Ensure .env files are in .gitignore. Use only .env.example with placeholder values. Implement secret management (e.g., HashiCorp Vault, cloud provider secret managers) for production deployments.
• Medium · Multiple Docker Configurations — build/docker/. Multiple Dockerfiles with different configurations (dev, canary, production, toolbox) increase the attack surface. Inconsistent security configurations across these files could lead to vulnerabilities. Fix: Audit all Dockerfile variants for security best practices. Ensure production Dockerfile uses minimal base images, non-root users, and security scanning. Document differences between configurations.
• Medium · AWS SDK Usage Without Explicit Security Review — go.mod (aws-sdk-go-v2 dependencies). The project uses AWS SDK v2 (aws-sdk-go-v2) with EC2 and STS services. Without visible IAM permission validation, there's risk of privilege escalation or unauthorized resource access. Fix: Implement least-privilege IAM policies for AWS credentials. Use AWS SigV4 signing. Enable CloudTrail logging. Regularly audit permissions and access patterns.
• Medium · Redis Event Broker Without Visible Authentication — internal/broker/redis_event.go. Redis event broker is used (internal/broker/redis_event.go) but connection security is not visible in provided files. Redis typically requires authentication configuration. Fix: Ensure Redis requires password authentication or runs behind a firewall. Use Redis AUTH command. Consider Redis over TLS/SSL (redis-tls). Implement network segmentation.
• Medium · Telegram Bot API Integration — go.mod (go-telegram-bot-api/telegram-bot-api/v5). Telegram bot API token is likely stored as environment variable or configuration. Exposure could allow bot hijacking or unauthorized notifications. Fix: Never hardcode API tokens. Use secret management. Implement token rotation. Log API access. Restrict bot permissions to minimum required scope.
• Medium · Cloud Provider Credentials Handling — build/infra/templates/, internal/cloud/. Support for AWS, GCP, Azure, DigitalOcean, Hetzner, and Linode indicates multiple cloud credential management points. Improper handling could expose cloud infrastructure. Fix: Use cloud provider IAM roles and service accounts instead of static credentials. Implement credential rotation. Use encrypted secret storage. Audit cloud access patterns.
• Low · Self-Update Mechanism — undefined. The Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.