Metadata-Version: 2.4
Name: r7_surcom_sdk
Version: 0.17.20
Summary: Python SDK used to interact and develop with Rapid7 Surface Command
Author-email: Rapid7 <integrationalliance@rapid7.com>
License-Expression: MIT
Keywords: rapid7,Rapid7,r7_surcom_sdk,r7-surcom-sdk,SurfaceCommand,Surface,Command,sdk
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.11
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Natural Language :: English
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jinja2~=3.1
Requires-Dist: PyYAML~=6.0
Requires-Dist: packaging~=26.0
Requires-Dist: argcomplete~=3.7
Requires-Dist: genson~=1.3
Requires-Dist: duckdb~=1.4
Requires-Dist: uv~=0.11.28
Requires-Dist: requests~=2.34.2
Requires-Dist: urllib3~=2.7.0
Provides-Extra: debug
Requires-Dist: debugpy~=1.8; extra == "debug"
Provides-Extra: developer
Requires-Dist: pytest; extra == "developer"
Requires-Dist: tox; extra == "developer"
Requires-Dist: pre-commit; extra == "developer"
Requires-Dist: pip-tools; extra == "developer"
Dynamic: license-file

# 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](https://github.com/rapid7/r7-surcom-connectors).

## Getting Started

1. Install the SDK:

   ```bash
   pip install r7-surcom-sdk
   ```

2. [Configure the SDK](https://docs.rapid7.com/surface-command/build-custom-connectors/#install-and-configure-the-sdk) with your API key

3. [Build your first connector](https://docs.rapid7.com/surface-command/build-custom-connectors/#build-an-example-connector) by following our tutorial

4. [Contribute](https://github.com/rapid7/r7-surcom-connectors?tab=contributing-ov-file) to our open source connectors or share your own connector with the community! 

## Documentation

- [Troubleshoot connector issues](https://docs.rapid7.com/surface-command/build-custom-connectors/#troubleshoot-your-connector)
- [Understand the Attack Surface Management type system](https://docs.rapid7.com/surface-command/asm-type-system)


## Changes

<!--
All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-->

### [0.17.20](https://pypi.org/project/r7-surcom-sdk/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](https://pypi.org/project/r7-surcom-sdk/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](https://pypi.org/project/r7-surcom-sdk/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](https://pypi.org/project/r7-surcom-sdk/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.
