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

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.

Metadata

Release files for r7-surcom-sdk 0.18.23

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.18.23
File Size Uploaded Provenance Actions
r7_surcom_sdk-0.18.23.tar.gz 681.1 kB Without provenance Details for r7_surcom_sdk-0.18.23.tar.gz

Built distribution (wheel)

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

Total release size: 1.4 MB

Release files / r7_surcom_sdk-0.18.23.tar.gz

Download URL r7_surcom_sdk-0.18.23.tar.gz
Size 681.1 kB
Tags Source
SHA-256 checksum
How to use checksums
378312771faa10f71b22f8c27ba62bf3888206362dc2ce0c1a5c5f9fde32e12a
BLAKE2b-256 checksum
How to use checksums
3675ecaea3fad4612cc4e6b231d5f9519ddc3de99489a29b59fa22e222f2dd07
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.18.23-py3-none-any.whl

Download URL r7_surcom_sdk-0.18.23-py3-none-any.whl
Size 739.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
76c3c5d130c70bd7db127bc86e9f0d7b543327e2b89f4df042e605642a185cd0
BLAKE2b-256 checksum
How to use checksums
9b998eca14f980411c2eec1a3196929a3d64b92aa50df94492d4a2b20c0a13c7
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.18.23

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