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
-
Install the SDK:
pip install r7-surcom-sdk
-
Configure the SDK with your API key
-
Build your first connector by following our tutorial
-
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=VALUEfor 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 optionalos_level_dependencieslist of OS packages installed withapt-getin the Orchestrator plugin andinvokeDocker images (not installed in SaaS; gate code using them withis_orchestrator()).connector invoke:- now runs
validatebefore building the image, with a new--skip-validateoption. - new repeatable
--add-host HOST:IPoption to add entries to the container's/etc/hosts.
- now runs
- Agent Skills: new
--claudeflag to also install the skills to~/.claude/skillsfor use with Claude Code.
Changed
- Deps: bumped
packaging(→ 26.3),genson(→ 1.4),duckdb(→ 2.0),uv(→ 0.13.5),urllib3(→ 2.8.0) anddebugpy(→ 1.8.22), and pinnedcertifi >= 2026.10.19to resolve vulnerabilities. Orchestrator plugin deps bumpedinsightconnect-plugin-runtime(→ 6.6.1) andcryptography(→ 50.0.2).
0.18.23 - 2026-09-28
Added
connector.spec: support fordepends_on(aliased withdepends-onfor 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-apipackage is used. - Orchestrator: Dockerfile template bumped to the latest
insightconnectimage for Python 3.13 support.
0.17.20 - 2026-07-14
Added
- MockServer: new
mockserver loadcommand. connector invoke --extra-volume: support for mounting additional volumes to the invoked Docker container.connector invoke --env-var: support for injecting environment variables (asKEY=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
.appsuffix). - required-keys validation on the type checker.
privileged_access_managementaccepted as a valid category.
- Docs:
Required?column,Valid Valuescolumn for enum settings, bold setting titles;Componentsand requirements sections only rendered when non-empty. - Package (Orchestrator):
- manually install the latest
certifiwhen building for orchestrator. - copy
.json/.yamlfiles (and jinja2 templates in subdirs) from the functions directory. - copy
types/to the pluginutil/directory. - no longer ignore files starting with
__(still ignores__init__.py).
- manually install the latest
- Manifest: support legacy
testfunction id,legacy_idproperty, and customsecret_reference. - Plugin:
connector_typeis now passed down; handle mismatched legacy function parameter vs. setting name. - Import: install unique types when importing data.
- Hidden settings: pass through
x-samos-hiddensettings. - Skills:
sc-connectorsupdated with the new PAM category.
Changed
- Legacy validation: improved wording and deduplicated checks.
surcom_api:import_idsare now URL-escaped in requests (they can contain/).- Deps: bumped
packaging(→ 26.0),argcomplete(→ 3.7),uv(→ 0.11.28),requests(→ 2.34.2), andurllib3(→ 2.7.0),requests/urllib3were 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_imageconfig that skips producing a.tarfile; combine connector + plugin deps viauv; dep dry-run runs inside apython:3.11container. sdk_helpers: newget_path_to_functions_dirhelper and legacy-to-plugin building support.sdk_config: new method to add a config to the root section.- Validation: new
iconvalidation. - Docs: handle
communityas an author. - Plugin Wrapper: extra error handling for improved logging.
- Codegen: uses latest deps when compiling requirements.
- Packaging:
.txtfiles now included in package data;insightconnect-plugin-runtimebumped to6.4.4.
Fixed
- Plugin: return an empty
dict/listwhen a connector returnsNone/nothing; do not raise if there is notypes/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 tosurcom_api. Tutorial andconnector_idnow share the same lookup logic.- Orchestrator: when a
build-numberis provided,+customis no longer appended.
Changed
- ext lib: skipped entirely for vendored connectors.
- Deps:
uvupdated to0.11.6;requestsbumped.
Removed
- Validate: removed the
betavalidation (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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.