Surface Command SDK

The surcom-sdk helps you build data connectors for the Rapid7 Surface Command platform.

Source code for all connectors is available in our GitHub repository.

Getting Started

1. Install the SDK:

   pip install r7-surcom-sdk
   

2. Configure the SDK with your API key

3. Build your first connector by following our tutorial

4. Contribute to our open source connectors or share your own connector with the community!

Documentation

• Troubleshoot connector issues
• Understand the Attack Surface Management type system

Changes

0.17.20 - 2026-07-14

Added

• MockServer: new mockserver load command.
• connector invoke --extra-volume: support for mounting additional volumes to the invoked Docker container.
• connector invoke --env-var: support for injecting environment variables (as KEY=VALUE) into the invoked Docker container.
• Validate:
  • line-length check (max 72-byte lines for signed connectors; JAR manifest max 67).
  • module folder must match the connector directory name (handles .app suffix).
  • required-keys validation on the type checker.
  • privileged_access_management accepted as a valid category.
• Docs: Required? column, Valid Values column for enum settings, bold setting titles; Components and requirements sections only rendered when non-empty.
• Package (Orchestrator):
  • manually install the latest certifi when building for orchestrator.
  • copy .json/.yaml files (and jinja2 templates in subdirs) from the functions directory.
  • copy types/ to the plugin util/ directory.
  • no longer ignore files starting with __ (still ignores __init__.py).
• Manifest: support legacy test function id, legacy_id property, and custom secret_reference.
• Plugin: connector_type is now passed down; handle mismatched legacy function parameter vs. setting name.
• Import: install unique types when importing data.
• Hidden settings: pass through x-samos-hidden settings.
• Skills: sc-connectors updated with the new PAM category.

Changed

• Legacy validation: improved wording and deduplicated checks.
• surcom_api: import_ids are now URL-escaped in requests (they can contain /).
• Deps: bumped packaging (→ 26.0), argcomplete (→ 3.7), uv (→ 0.11.28), requests (→ 2.34.2), and urllib3 (→ 2.7.0), requests/urllib3 were also unpinned from exact versions to compatible-release specifiers.

0.16.19 - 2026-05-05

Added

• Orchestrator / Plugin conversion: build a plugin from a Legacy Connector; support connectors with a custom tarball; new save_docker_image config that skips producing a .tar file; combine connector + plugin deps via uv; dep dry-run runs inside a python:3.11 container.
• sdk_helpers: new get_path_to_functions_dir helper and legacy-to-plugin building support.
• sdk_config: new method to add a config to the root section.
• Validation: new icon validation.
• Docs: handle community as an author.
• Plugin Wrapper: extra error handling for improved logging.
• Codegen: uses latest deps when compiling requirements.
• Packaging: .txt files now included in package data; insightconnect-plugin-runtime bumped to 6.4.4.

Fixed

• Plugin: return an empty dict/list when a connector returns None/nothing; do not raise if there is no types/ directory.
• Orchestrator: resolve settings when converting to a plugin; connector deps now take precedence over plugin deps.

0.15.18 - 2026-04-14

Added

• data delete: new command for deleting imported data, with import-id lookup helpers added to surcom_api. Tutorial and connector_id now share the same lookup logic.
• Orchestrator: when a build-number is provided, +custom is no longer appended.

Changed

• ext lib: skipped entirely for vendored connectors.
• Deps: uv updated to 0.11.6; requests bumped.

Removed

• Validate: removed the beta validation (tests retained).

0.14.16 - 2026-03-23

Added

• Agent Skills: new sc-surcom-sdk, sc-cypher-queries, and sc-connectors skills. sc-surcom-sdk includes a config overview, connector-generation guidance, and a list of valid URLs. sc-cypher-queries and sc-type-system now include a derived-properties reference.
• KeyboardInterrupt: Ctrl+C is now handled gracefully across commands.
• config init: no longer prompts per-skill — installs all in one go.
• validate: checks that every type in the types/ directory is defined.

Changed

• sc-type-system: cypher query details moved out into the dedicated sc-cypher-queries skill.