How phantomcyber/splunk-soar-sdk works
1. Repository purpose
- This is the Splunk SOAR SDK, a Python library and command-line tool for building, converting, packaging, and testing Splunk SOAR apps.
- The main runtime package lives in src/soar_sdk; the repo also includes documentation, templates, tests, CI workflows, and a small separate MCP server under mcp_server/.
2. Primary product boundary: the SDK package
- src/soar_sdk is the core distribution.
- It exposes the app authoring surface (App, decorators, asset/action/params models), runtime integration with Splunk SOAR, and supporting utilities for auth, rendering, packaging, and CLI workflows.
- The README example reflects the intended architecture: app authors define an asset model, register actions with decorators, then run app.cli() to use the SDK tooling.
3. App authoring and runtime model
- app.py, asset.py, params.py, action_results.py, models/*, and input_spec.py define the typed object model used by app developers.
- actions_manager.py, abstract.py, and app_client.py bridge user-defined app code to the SOAR execution environment.
- async_utils.py, paths.py, field_utils.py, types.py, and compat.py provide supporting runtime behavior and cross-version helpers.
4. Decorator-driven registration layer
- src/soar_sdk/decorators is the main declaration mechanism for app behavior.
- Decorators such as action, test_connectivity, on_poll, on_es_poll, webhook, view_handler, and make_request annotate user functions and turn them into SDK-managed app endpoints or execution hooks.
- This is the central “user code to framework metadata” boundary.
5. Metadata and manifest generation
- src/soar_sdk/meta models the app and its declared capabilities in a normalized internal form.
- Subpackages under meta/dependencies handle dependency resolution and lockfile/package source interpretation, which is important for converting app projects and generating deployable metadata.
- The CLI manifest tools under src/soar_sdk/cli/manifests serialize and deserialize app manifest data, process notices, and support conversion workflows.
6. Authentication and API integration
- src/soar_sdk/auth contains the auth flows, client factories, token/certificate models, and httpx integration used for SOAR and related API authentication.
- src/soar_sdk/apis exposes typed client wrappers for platform resources such as artifact, container, and vault.
- These modules form the outbound integration layer from an app to Splunk SOAR services.
7. Webhooks, polling, and event-driven execution
- src/soar_sdk/webhooks handles webhook routing and webhook models.
- The poll-related decorators in decorators/on_poll.py and decorators/on_es_poll.py define scheduled or event-stream driven ingestion paths.
- This separates reactive ingress mechanisms from action execution, which matters for diagramming how external events enter the app.
8. Custom views and templated UI rendering
- src/soar_sdk/views and src/soar_sdk/templates implement the app’s custom-view subsystem.
- The view parser, component registry, template renderer, and template filters translate SDK view definitions into HTML/UI fragments.
- Built-in components like the pie chart live under views/components, while reusable base templates live under templates/base and widget templates under templates/widgets.
9. Code generation and app scaffolding
- src/soar_sdk/code_renderers generates starter files and config for new apps and conversions, including pyproject.toml, .pre-commit-config.yaml, app/action/asset code, and supporting templates.
- src/soar_sdk/cli/init is the scaffolding entrypoint, while src/soar_sdk/app_templates/basic_app provides a ready-made starter project layout.
- This is the main “project creation” boundary between the SDK and the user’s generated app repository.
10. CLI as the operational front door
- src/soar_sdk/cli/cli.py is the top-level soarapps command.
- Subcommands are organized by purpose: init for project creation, convert/manifest tooling for migration and metadata handling, package for packaging-related tasks, and test for SDK-assisted validation.
- app_cli_runner.py and cli/utils.py support execution of app-side flows from the command line.
11. Legacy compatibility and shims
- src/soar_sdk/shims/phantom and src/soar_sdk/shims/phantom_common provide compatibility with older Phantom/BaseConnector-style apps and internal interfaces.
- These shims are crucial for the conversion story: they let the SDK understand or emulate older app structures during migration and packaging.
12. Extras and specialized processors
- src/soar_sdk/extras/email adds email parsing/processing support as a focused feature area.
- This is a distinct functional subsystem, not part of the core app lifecycle, and likely supports specialized action inputs or helper workflows.
13. MCP test assistant sidecar
- mcp_server/ is a separate Python package containing soar_test_assistant.
- It appears to provide a test/analyzer service used for validation or local assistance, with its own pyproject.toml, tests, and install script.
- Architecturally, treat it as an auxiliary tool rather than part of the main SDK runtime.
14. Tests, fixtures, and example app topology
- tests/ is extensive and mirrors the SDK surface: unit tests for core models, CLI, auth, views, webhooks, renderers, and integration tests against example apps.
- tests/example_app* contains realistic app projects used to validate conversion, packaging, webhook support, OAuth, and state handling.
- This test layout is useful for architecture diagrams because it reveals the intended boundaries: core SDK, generated app projects, and runtime integration with Splunk SOAR.
15. Docs and release automation
- docs/ is the authoritative design and user-facing architecture documentation for app structure, authentication, custom views, CLI, and getting started flows.
- .github/workflows covers code quality, integration tests, docs generation, semantic release, and commit hygiene; .releaserc and commitlint.config.js support automated versioning and release management.
- These don’t affect runtime behavior, but they do define the repository’s delivery pipeline and quality gates.
Main entry points: actions_manager.py Runtime bridge · meta Metadata · soar_sdk soar_sdk · cli.py soarapps
Components 21
SDK core
Primary Python package for app authoring, runtime integration, and metadata generation.
- soar_sdk · Core distribution boundary for the SDK.
src/soar_sdk - App model · Typed app, asset, params, action results, and input specification objects.
src/soar_sdk/app.py - Decorators · Action, connectivity, polling, webhook, view, and request decorators that register app behavior.
src/soar_sdk/decorators - Runtime bridge · Adapts user app code to the SOAR runtime and action execution model.
src/soar_sdk/actions_manager.py - Metadata · Normalized app, action, webhook, and dependency metadata used for packaging and conversion.
src/soar_sdk/meta - Dependencies · Lockfile, package source, wheel, and dependency interpretation utilities.
src/soar_sdk/meta/dependencies - Auth · Authentication flows, token and certificate models, and httpx integration for SOAR APIs.
src/soar_sdk/auth - API clients · Typed wrappers for platform resources such as artifacts, containers, and vault.
src/soar_sdk/apis - Webhooks · Webhook models and routing for event-driven app entrypoints.
src/soar_sdk/webhooks - Email extras · Email parsing and processing support for specialized workflows.
src/soar_sdk/extras/email
CLI
Command-line entrypoints and subcommands for init, manifest handling, packaging, and testing.
- soarapps · Top-level CLI front door for SDK operations.
src/soar_sdk/cli/cli.py - Init · Project creation and scaffolding wizard.
src/soar_sdk/cli/init - Manifests · Manifest serialization, deserialization, notices, and conversion helpers.
src/soar_sdk/cli/manifests - Package · Packaging-related CLI operations and utilities.
src/soar_sdk/cli/package - Test · SDK-assisted validation and test execution from the command line.
src/soar_sdk/cli/test
Views & templates
Custom view rendering, template parsing, and reusable UI fragments.
Compatibility
Legacy Phantom/BaseConnector shims and migration helpers.
- Phantom shims · Compatibility wrappers for older Phantom/BaseConnector-style apps and migration support.
src/soar_sdk/shims
Auxiliary tools
Sidecar MCP assistant and generated app scaffolding.
- Code renderers · Generates app files and project config for new apps and conversion workflows.
src/soar_sdk/code_renderers - MCP assistant · Auxiliary test assistant service packaged separately from the SDK runtime.
mcp_server
Test fixtures
Representative example apps used to validate the SDK surface and conversion flows.
- Example apps · Representative app projects used by tests to validate conversion, packaging, auth, webhooks, and state handling.
tests/example_app
Connections 24
- soar_sdk → App model: exposes · The package exports the primary app authoring surface.
- soar_sdk → Decorators: exposes · Decorator APIs are part of the main public surface.
- soar_sdk → Runtime bridge: hosts · Core runtime coordination lives inside the SDK package.
- soar_sdk → Metadata: models · Metadata is derived from the app and decorator declarations.
- Metadata → Dependencies: resolves · Dependency metadata feeds lockfile and package-source handling.
- Decorators → Metadata: describes · Decorators turn user functions into normalized capability metadata.
- App model → Runtime bridge: invoked by · App objects are executed through the runtime bridge and action manager.
- Runtime bridge → Auth: uses · Runtime integrations rely on authentication flows and HTTP clients.
- Runtime bridge → API clients: calls · App execution talks to platform resources through typed API clients.
- Runtime bridge → Webhooks: receives · Webhook and poll entrypoints feed events into app execution.
- Webhooks → Decorators: registered by · Webhook-related decorators declare inbound event handlers.
- Decorators → Views: declares · View handlers and custom view declarations bind into the UI subsystem.
- Views → Templates: renders with · View parsing and rendering use shared HTML/template assets.
- Code renderers → Init: powers · Scaffolding generation is driven from the init workflow.
- soarapps → Init: dispatches · Top-level CLI routes init commands to the scaffolding subcommand.
- soarapps → Manifests: dispatches · Top-level CLI routes manifest tooling to the manifests subcommand.
- soarapps → Package: dispatches · Top-level CLI routes packaging tasks to the package subcommand.
- soarapps → Test: dispatches · Top-level CLI routes validation tasks to the test subcommand.
- Manifests → Metadata: serializes · Manifest tooling reads and writes the normalized metadata model.
- Phantom shims → Runtime bridge: compatibility · Legacy interfaces are adapted to the modern SDK runtime.
- Phantom shims → Metadata: migrates · Shims help conversion and packaging understand older app structures.
- Email extras → App model: extends · Email processing provides specialized data handling for app workflows.
- MCP assistant → Test: assists · The sidecar service appears to support analysis and local test assistance.
- Example apps → Code renderers: validated by · Representative generated apps exercise scaffolding and packaging behavior.