Osmedeus Documentation

The Osmedeus repository is organized into several key directories that define its functionality:

• cmd/osmedeus/: The main application entry point.
• internal/: Contains private packages including core logic (core), execution engine (executor), database management (database), cloud provisioning (cloud), and workflow linting (linter).
• pkg/: Contains public packages for the cli (Cobra-based) and the server (Fiber-based REST API).
• public/: Holds public assets such as examples and presets.
• test/: Contains E2E, integration, and test data.
• lib/: Shared library utilities.
• docs/: API documentation.

Osmedeus is built using a layered architecture consisting of:

1. CLI / API Layer: The interface via pkg/cli and pkg/server.
2. Executor Layer: Manages the Executor, Dispatcher, and various Step Executors (e.g., bash, function, foreach).
3. Runner Layer: Provides execution environments including Host Runner, Docker Runner, and SSH Runner.
4. Support Systems: Includes the Template Engine, Functions Registry, and Scheduler (triggers).
5. Data Layer: Handles the Parser/Loader, Database (SQLite/PG), and Workspace Manager.

Submit scans to a distributed worker pool. This requires the Osmedeus server to be started with the --master flag. Each target in a targets array is submitted as a separate task to the worker queue.

# Multiple targets distributed across workers
curl -X POST http://localhost:8002/osm/api/runs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "subdomain-enum",
    "targets": ["example.com", "test.com", "demo.com"],
    "run_mode": "distributed",
    "priority": "high"
  }'

To extend the Osmedeus JavaScript runtime with new functions, follow these three steps:

1. Implement the function in Go: Add the logic in the appropriate file (e.g., internal/functions/file_functions.go) using the goja.FunctionCall signature.
2. Register the function: In goja_runtime.go, map the function name to the implementation using vm.Set.
3. Define the constant: Add the function name as a constant in constants.go to ensure consistency.

Example implementation:

// 1. Implementation
func (vf *vmFunc) myNewFunction(call goja.FunctionCall) goja.Value {
    arg := call.Argument(0).String()
    // ... implementation
    return vf.vm.ToValue(output)
}

// 2. Registration in goja_runtime.go
_ = vm.Set("my_new_function", vf.myNewFunction)

// 3. Constant in constants.go
const FnMyNewFunction = "my_new_function"

To manage costs and efficiency when using Osmedeus Cloud, follow these best practices:

• Cost Management: Always set cost limits before large-scale scans. Use --auto-destroy to prevent forgotten instances from accruing charges, and use spot instances for non-critical scans to achieve 70-80% savings.
• Efficiency: Use --reuse to avoid re-provisioning infrastructure during iterative work. To reduce setup time from ~5 minutes to ~30 seconds, use custom snapshots with your required tools pre-installed.
• Scaling & Monitoring: Start small by testing with 1 instance before scaling up. Regularly run cloud list to verify there is no orphaned infrastructure.

To extend the linter, implement the LinterRule interface in internal/linter/rules.go and register it in GetDefaultRules().

1. Define your struct and implement Name(), Description(), Severity(), and Check().
2. Add an instance of your rule to the GetDefaultRules() slice.

// 1. Create the rule
type MyNewRule struct{}

func (r *MyNewRule) Name() string        { return "my-new-rule" }
func (r *MyNewRule) Description() string { return "Detects my issue" }
func (r *MyNewRule) Severity() Severity  { return SeverityWarning }

func (r *MyNewRule) Check(wast *WorkflowAST) []LintIssue {
    var issues []LintIssue
    // ... implementation
    return issues
}

// 2. Register in GetDefaultRules()
func GetDefaultRules() []LinterRule {
    return []LinterRule{
        &MyNewRule{},
    }
}

Cloud configurations are managed via the cloud config command. The system supports environment variable resolution within configuration values using the ${VAR_NAME} syntax. This allows you to securely inject credentials like API tokens.

To set a provider and an environment variable for a token:

osmedeus cloud config set defaults.provider digitalocean
osmedeus cloud config set providers.digitalocean.token ${DIGITALOCEAN_TOKEN}
osmedeus cloud config show

Manage existing cloud instances or perform a full cleanup of your GCP infrastructure.

List Infrastructure

osmedeus cloud list

Destroy Instances

# Destroy a specific instance by ID
osmedeus cloud destroy <infra-id>

# Destroy all instances (Nuclear option)
osmedeus cloud destroy all --force

Persistent Recon (Reuse Instances)

To save setup time, create instances once and reuse them for multiple scans:

# Create instances once
osmedeus cloud create --provider gcp -n 3

# Run scans using --reuse
osmedeus cloud run -f fast -t target1.com --reuse
osmedeus cloud run -f fast -t target2.com --reuse

# Destroy at end of day
osmedeus cloud destroy all --force