Skip to main content

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

Changes

0.19.0

Added

  • data query: new command to run a Cypher query against Surface Command from the CLI (max 500 results), with repeatable -p/--parameters KEY=VALUE for parameterized queries.
  • logs: new command that takes an Execution ID and prints the workflow's logs, waiting until the workflow finishes if it is still running.
  • connector.spec: new optional os_level_dependencies list of OS packages installed with apt-get in the Orchestrator plugin and invoke Docker images (not installed in SaaS; gate code using them with is_orchestrator()).
  • connector invoke:
    • now runs validate before building the image, with a new --skip-validate option.
    • new repeatable --add-host HOST:IP option to add entries to the container's /etc/hosts.
  • Agent Skills: new --claude flag to also install the skills to ~/.claude/skills for use with Claude Code.

Changed

  • Deps: bumped packaging (→ 26.3), genson (→ 1.4), duckdb (→ 2.0), uv (→ 0.13.5), urllib3 (→ 2.8.0) and debugpy (→ 1.8.22), and pinned certifi >= 2026.10.19 to resolve vulnerabilities. Orchestrator plugin deps bumped insightconnect-plugin-runtime (→ 6.6.1) and cryptography (→ 50.0.2).

0.18.23 - 2026-09-28

Added

  • connector.spec: support for depends_on (aliased with depends-on for backwards compatibility).

Changed

  • Orchestrator: when building the docker image, dependencies are now resolved from Artifactory first and PyPI second so the latest internal noetic-connector-api package is used.
  • Orchestrator: Dockerfile template bumped to the latest insightconnect image for Python 3.13 support.

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).

Metadata

Release files for r7-surcom-sdk 0.19.24

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for r7-surcom-sdk 0.19.24
File Size Uploaded Provenance Actions
r7_surcom_sdk-0.19.24.tar.gz 687.3 kB Without provenance Details for r7_surcom_sdk-0.19.24.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for r7-surcom-sdk 0.19.24
File Interpreter ABI Platform Actions
r7_surcom_sdk-0.19.24-py3-none-any.whl Python 3 none any Details for r7_surcom_sdk-0.19.24-py3-none-any.whl

Total release size: 1.4 MB

Release files / r7_surcom_sdk-0.19.24.tar.gz

Download URL r7_surcom_sdk-0.19.24.tar.gz
Size 687.3 kB
Tags Source
SHA-256 checksum
How to use checksums
698dac4a8311b13e30c1adec8f4276d07fc44b4d57762406886a9f1eb5e53ecb
BLAKE2b-256 checksum
How to use checksums
17143b95fc56ec7f136c9d8632d255c80d544e947c25cae8e5d15164aee3c110
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.11.15

Release files / r7_surcom_sdk-0.19.24-py3-none-any.whl

Download URL r7_surcom_sdk-0.19.24-py3-none-any.whl
Size 747.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
dfdca7890f519da756b48510bfadf6490561050f3935eb71b9aa30107eb59194
BLAKE2b-256 checksum
How to use checksums
8a1148ce2fecec65c32d6319b8db63d950ca24e3692d837f95a7eb7398be01b6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.11.15

Security for r7-surcom-sdk 0.19.24

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page