socketsecurity 2.2.59__tar.gz → 2.2.62__tar.gz

{socketsecurity-2.2.59 → socketsecurity-2.2.62}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: socketsecurity
-Version: 2.2.59
+Version: 2.2.62
 Summary: Socket Security CLI for CI/CD
 Project-URL: Homepage, https://socket.dev
 Author-email: Douglas Coburn <douglas@socket.dev>
@@ -35,12 +35,13 @@ Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.10
 Requires-Dist: bs4>=0.0.2
 Requires-Dist: gitpython
+Requires-Dist: markdown>=3.10
 Requires-Dist: mdutils
 Requires-Dist: packaging
 Requires-Dist: prettytable
 Requires-Dist: python-dotenv
 Requires-Dist: requests
-Requires-Dist: socketdev<4.0.0,>=3.0.22
+Requires-Dist: socketdev<4.0.0,>=3.0.25
 Provides-Extra: dev
 Requires-Dist: hatch; extra == 'dev'
 Requires-Dist: pre-commit; extra == 'dev'
@@ -158,14 +159,14 @@ socketcli [-h] [--api-token API_TOKEN] [--repo REPO] [--repo-is-public] [--branc
           [--only-facts-file] [--version]
 ````
 
-If you don't want to provide the Socket API Token every time then you can use the environment variable `SOCKET_SECURITY_API_KEY`
+If you don't want to provide the Socket API Token every time then you can use the environment variable `SOCKET_SECURITY_API_TOKEN`
 
 ### Parameters
 
 #### Authentication
-| Parameter   | Required | Default | Description                                                                     |
-|:------------|:---------|:--------|:--------------------------------------------------------------------------------|
-| --api-token | False    |         | Socket Security API token (can also be set via SOCKET_SECURITY_API_KEY env var) |
+| Parameter   | Required | Default | Description                                                                       |
+|:------------|:---------|:--------|:----------------------------------------------------------------------------------|
+| --api-token | False    |         | Socket Security API token (can also be set via SOCKET_SECURITY_API_TOKEN env var) |
 
 #### Repository
 | Parameter        | Required | Default | Description                                                             |
@@ -278,15 +279,113 @@ Example `SOCKET_JIRA_CONFIG_JSON` value
 
 | Environment Variable     | Required | Default | Description                        |
 |:-------------------------|:---------|:--------|:-----------------------------------|
-| SOCKET_SLACK_ENABLED     | False    | false   | Enables/Disables the Slack Plugin  |
-| SOCKET_SLACK_CONFIG_JSON | True     | None    | Required if the Plugin is enabled. |
+| SOCKET_SLACK_CONFIG_JSON | False    | None    | Slack configuration (enables plugin when set). Supports webhook or bot mode. Alternatively, use --slack-webhook CLI flag for simple webhook mode. |
+| SOCKET_SLACK_BOT_TOKEN   | False    | None    | Slack Bot User OAuth Token (starts with `xoxb-`). Required when using bot mode. |
 
-Example `SOCKET_SLACK_CONFIG_JSON` value
+**Slack supports two modes:**
+
+1. **Webhook Mode** (default): Posts to incoming webhooks
+2. **Bot Mode**: Posts via Slack API with bot token authentication
+
+###### Webhook Mode Examples
+
+Simple webhook:
+
+````json
+{"url": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"}
+````
+
+Multiple webhooks with advanced filtering:
 
 ````json
-{"url": "https://REPLACE_ME_WEBHOOK"}
+{
+  "mode": "webhook",
+  "url": [
+    {
+      "name": "prod_alerts",
+      "url": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
+    },
+    {
+      "name": "critical_only",
+      "url": "https://hooks.slack.com/services/YOUR/OTHER/WEBHOOK/URL"
+    }
+  ],
+  "url_configs": {
+    "prod_alerts": {
+      "reachability_alerts_only": true,
+      "severities": ["high", "critical"]
+    },
+    "critical_only": {
+      "severities": ["critical"]
+    }
+  }
+}
 ````
 
+###### Bot Mode Examples
+
+**Setting up a Slack Bot:**
+1. Go to https://api.slack.com/apps and create a new app
+2. Under "OAuth & Permissions", add the `chat:write` bot scope
+3. Install the app to your workspace and copy the "Bot User OAuth Token"
+4. Invite the bot to your channels: `/invite @YourBotName`
+
+Basic bot configuration:
+
+````json
+{
+  "mode": "bot",
+  "bot_configs": [
+    {
+      "name": "security_alerts",
+      "channels": ["security-alerts", "dev-team"]
+    }
+  ]
+}
+````
+
+Bot with filtering (reachability-only alerts):
+
+````json
+{
+  "mode": "bot",
+  "bot_configs": [
+    {
+      "name": "critical_reachable",
+      "channels": ["security-critical"],
+      "severities": ["critical", "high"],
+      "reachability_alerts_only": true
+    },
+    {
+      "name": "all_alerts",
+      "channels": ["security-all"],
+      "repos": ["myorg/backend", "myorg/frontend"]
+    }
+  ]
+}
+````
+
+Set the bot token:
+```bash
+export SOCKET_SLACK_BOT_TOKEN="xoxb-your-bot-token-here"
+```
+
+**Configuration Options:**
+
+Webhook mode (`url_configs`):
+- `reachability_alerts_only` (boolean, default: false): When `--reach` is enabled, only send blocking alerts (error=true) from diff scans
+- `repos` (array): Only send alerts for specific repositories (e.g., `["owner/repo1", "owner/repo2"]`)
+- `alert_types` (array): Only send specific alert types (e.g., `["malware", "typosquat"]`)
+- `severities` (array): Only send alerts with specific severities (e.g., `["high", "critical"]`)
+
+Bot mode (`bot_configs` array items):
+- `name` (string, required): Friendly name for this configuration
+- `channels` (array, required): Channel names (without #) where alerts will be posted
+- `severities` (array, optional): Only send alerts with specific severities (e.g., `["high", "critical"]`)
+- `repos` (array, optional): Only send alerts for specific repositories
+- `alert_types` (array, optional): Only send specific alert types
+- `reachability_alerts_only` (boolean, default: false): Only send reachable vulnerabilities when using `--reach`
+
 ## Automatic Git Detection
 
 The CLI now automatically detects repository information from your git environment, significantly simplifying usage in CI/CD pipelines:
@@ -547,7 +646,8 @@ Implementation targets:
 ### Environment Variables
 
 #### Core Configuration
-- `SOCKET_SECURITY_API_KEY`: Socket Security API token (alternative to --api-token parameter)
+- `SOCKET_SECURITY_API_TOKEN`: Socket Security API token (alternative to --api-token parameter)
+  - For backwards compatibility, also accepts: `SOCKET_SECURITY_API_KEY`, `SOCKET_API_KEY`, `SOCKET_API_TOKEN`
 - `SOCKET_SDK_PATH`: Path to local socketdev repository (default: ../socketdev)
 
 #### GitLab Integration

{socketsecurity-2.2.59 → socketsecurity-2.2.62}/README.md

@@ -101,14 +101,14 @@ socketcli [-h] [--api-token API_TOKEN] [--repo REPO] [--repo-is-public] [--branc
           [--only-facts-file] [--version]
 ````
 
-If you don't want to provide the Socket API Token every time then you can use the environment variable `SOCKET_SECURITY_API_KEY`
+If you don't want to provide the Socket API Token every time then you can use the environment variable `SOCKET_SECURITY_API_TOKEN`
 
 ### Parameters
 
 #### Authentication
-| Parameter   | Required | Default | Description                                                                     |
-|:------------|:---------|:--------|:--------------------------------------------------------------------------------|
-| --api-token | False    |         | Socket Security API token (can also be set via SOCKET_SECURITY_API_KEY env var) |
+| Parameter   | Required | Default | Description                                                                       |
+|:------------|:---------|:--------|:----------------------------------------------------------------------------------|
+| --api-token | False    |         | Socket Security API token (can also be set via SOCKET_SECURITY_API_TOKEN env var) |
 
 #### Repository
 | Parameter        | Required | Default | Description                                                             |
@@ -221,15 +221,113 @@ Example `SOCKET_JIRA_CONFIG_JSON` value
 
 | Environment Variable     | Required | Default | Description                        |
 |:-------------------------|:---------|:--------|:-----------------------------------|
-| SOCKET_SLACK_ENABLED     | False    | false   | Enables/Disables the Slack Plugin  |
-| SOCKET_SLACK_CONFIG_JSON | True     | None    | Required if the Plugin is enabled. |
+| SOCKET_SLACK_CONFIG_JSON | False    | None    | Slack configuration (enables plugin when set). Supports webhook or bot mode. Alternatively, use --slack-webhook CLI flag for simple webhook mode. |
+| SOCKET_SLACK_BOT_TOKEN   | False    | None    | Slack Bot User OAuth Token (starts with `xoxb-`). Required when using bot mode. |
 
-Example `SOCKET_SLACK_CONFIG_JSON` value
+**Slack supports two modes:**
+
+1. **Webhook Mode** (default): Posts to incoming webhooks
+2. **Bot Mode**: Posts via Slack API with bot token authentication
+
+###### Webhook Mode Examples
+
+Simple webhook:
+
+````json
+{"url": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"}
+````
+
+Multiple webhooks with advanced filtering:
 
 ````json
-{"url": "https://REPLACE_ME_WEBHOOK"}
+{
+  "mode": "webhook",
+  "url": [
+    {
+      "name": "prod_alerts",
+      "url": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
+    },
+    {
+      "name": "critical_only",
+      "url": "https://hooks.slack.com/services/YOUR/OTHER/WEBHOOK/URL"
+    }
+  ],
+  "url_configs": {
+    "prod_alerts": {
+      "reachability_alerts_only": true,
+      "severities": ["high", "critical"]
+    },
+    "critical_only": {
+      "severities": ["critical"]
+    }
+  }
+}
 ````
 
+###### Bot Mode Examples
+
+**Setting up a Slack Bot:**
+1. Go to https://api.slack.com/apps and create a new app
+2. Under "OAuth & Permissions", add the `chat:write` bot scope
+3. Install the app to your workspace and copy the "Bot User OAuth Token"
+4. Invite the bot to your channels: `/invite @YourBotName`
+
+Basic bot configuration:
+
+````json
+{
+  "mode": "bot",
+  "bot_configs": [
+    {
+      "name": "security_alerts",
+      "channels": ["security-alerts", "dev-team"]
+    }
+  ]
+}
+````
+
+Bot with filtering (reachability-only alerts):
+
+````json
+{
+  "mode": "bot",
+  "bot_configs": [
+    {
+      "name": "critical_reachable",
+      "channels": ["security-critical"],
+      "severities": ["critical", "high"],
+      "reachability_alerts_only": true
+    },
+    {
+      "name": "all_alerts",
+      "channels": ["security-all"],
+      "repos": ["myorg/backend", "myorg/frontend"]
+    }
+  ]
+}
+````
+
+Set the bot token:
+```bash
+export SOCKET_SLACK_BOT_TOKEN="xoxb-your-bot-token-here"
+```
+
+**Configuration Options:**
+
+Webhook mode (`url_configs`):
+- `reachability_alerts_only` (boolean, default: false): When `--reach` is enabled, only send blocking alerts (error=true) from diff scans
+- `repos` (array): Only send alerts for specific repositories (e.g., `["owner/repo1", "owner/repo2"]`)
+- `alert_types` (array): Only send specific alert types (e.g., `["malware", "typosquat"]`)
+- `severities` (array): Only send alerts with specific severities (e.g., `["high", "critical"]`)
+
+Bot mode (`bot_configs` array items):
+- `name` (string, required): Friendly name for this configuration
+- `channels` (array, required): Channel names (without #) where alerts will be posted
+- `severities` (array, optional): Only send alerts with specific severities (e.g., `["high", "critical"]`)
+- `repos` (array, optional): Only send alerts for specific repositories
+- `alert_types` (array, optional): Only send specific alert types
+- `reachability_alerts_only` (boolean, default: false): Only send reachable vulnerabilities when using `--reach`
+
 ## Automatic Git Detection
 
 The CLI now automatically detects repository information from your git environment, significantly simplifying usage in CI/CD pipelines:
@@ -490,7 +588,8 @@ Implementation targets:
 ### Environment Variables
 
 #### Core Configuration
-- `SOCKET_SECURITY_API_KEY`: Socket Security API token (alternative to --api-token parameter)
+- `SOCKET_SECURITY_API_TOKEN`: Socket Security API token (alternative to --api-token parameter)
+  - For backwards compatibility, also accepts: `SOCKET_SECURITY_API_KEY`, `SOCKET_API_KEY`, `SOCKET_API_TOKEN`
 - `SOCKET_SDK_PATH`: Path to local socketdev repository (default: ../socketdev)
 
 #### GitLab Integration

{socketsecurity-2.2.59 → socketsecurity-2.2.62}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "socketsecurity"
-version = "2.2.59"
+version = "2.2.62"
 requires-python = ">= 3.10"
 license = {"file" = "LICENSE"}
 dependencies = [
@@ -16,8 +16,9 @@ dependencies = [
     'GitPython',
     'packaging',
     'python-dotenv',
-    'socketdev>=3.0.22,<4.0.0',
+    "socketdev>=3.0.25,<4.0.0",
     "bs4>=0.0.2",
+    "markdown>=3.10",
 ]
 readme = "README.md"
 description = "Socket Security CLI for CI/CD"

socketsecurity-2.2.62/session.md

@@ -0,0 +1,127 @@
+# Session Directions: Add Slack Bot Mode Support
+
+## Context
+The Socket Python CLI currently supports Slack notifications via incoming webhooks. We need to add an alternative "bot" mode that uses a Slack App with Bot Token for more flexible channel routing.
+
+## Current Implementation
+- File: `socketsecurity/plugins/slack.py`
+- File: `socketsecurity/config.py`
+- Env var: `SOCKET_SLACK_CONFIG_JSON`
+- Current config uses `url` and `url_configs` for webhook routing
+
+## Requirements
+
+### 1. Add Mode Selection
+- Add top-level `mode` field to Slack config
+- Valid values: "webhook" (default), "bot"
+- Mode determines which authentication and routing method to use
+
+### 2. Webhook Mode (existing, default)
+```json
+{
+  "enabled": true,
+  "mode": "webhook",
+  "url": ["https://hooks.slack.com/..."],
+  "url_configs": {
+    "webhook_0": {"repos": ["repo1"], "severities": ["critical"]}
+  }
+}
+```
+Keep all existing webhook functionality unchanged.
+
+### 3. Bot Mode (new)
+```json
+{
+  "enabled": true,
+  "mode": "bot",
+  "bot_configs": [
+    {
+      "name": "critical_alerts",
+      "channels": ["security-alerts", "critical-incidents"],
+      "repos": ["prod-app"],
+      "severities": ["critical"],
+      "reachability_alerts_only": true
+    },
+    {
+      "name": "all_alerts", 
+      "channels": ["dev-alerts"],
+      "severities": ["high", "medium"]
+    }
+  ]
+}
+```
+
+- New env var: `SOCKET_SLACK_BOT_TOKEN` (Bot User OAuth Token starting with `xoxb-`)
+- Use `bot_configs` array instead of `url` + `url_configs`
+- Each bot_config has:
+  - `name`: identifier for logging
+  - `channels`: array of Slack channel names or IDs to post to
+  - All existing filter options: `repos`, `severities`, `alert_types`, `reachability_alerts_only`, `always_send_reachability`
+
+### 4. Channel Routing
+- Slack API accepts both channel names (without #) and channel IDs (C1234567890)
+- Recommend supporting both: try name first, fallback to ID if needed
+- API endpoint: `https://slack.com/api/chat.postMessage`
+- Request format:
+```python
+{
+    "channel": "channel-name",  # or "C1234567890"
+    "blocks": blocks
+}
+```
+- Headers: `{"Authorization": f"Bearer {bot_token}", "Content-Type": "application/json"}`
+
+### 5. Implementation Tasks
+
+#### config.py
+- No changes needed (config is loaded from JSON env var)
+
+#### slack.py
+1. Update `send()` method:
+   - Check `self.config.get("mode", "webhook")` 
+   - If "webhook": call existing `_send_webhook_alerts()` (refactor current logic)
+   - If "bot": call new `_send_bot_alerts()`
+
+2. Create `_send_bot_alerts()` method:
+   - Get bot token from env: `os.getenv("SOCKET_SLACK_BOT_TOKEN")`
+   - Validate token exists and starts with "xoxb-"
+   - Get `bot_configs` from config
+   - For each bot_config, filter alerts same way as webhooks
+   - For each channel in bot_config's channels array, post message via chat.postMessage API
+
+3. Create `_post_to_slack_api()` helper method:
+   - Takes bot_token, channel, blocks
+   - Posts to https://slack.com/api/chat.postMessage
+   - Returns response
+   - Log errors with channel name/ID for debugging
+
+4. Error handling:
+   - Log if bot token missing when mode is "bot"
+   - Handle API errors (invalid channel, missing permissions, rate limits)
+   - Parse Slack API response JSON (it returns 200 with error in body)
+
+5. Reuse existing:
+   - All filtering logic (`_filter_alerts`)
+   - All block building (`create_slack_blocks_from_diff`, `_create_reachability_slack_blocks_from_structured`)
+   - All reachability data loading
+
+### 6. Testing Considerations
+- Test both modes don't interfere with each other
+- Test channel name resolution
+- Test channel ID usage
+- Test multiple channels per bot_config
+- Test error handling when bot token invalid or missing
+- Verify block count limits still respected (50 blocks)
+
+### 7. Documentation Updates (README.md)
+Add bot mode configuration examples and SOCKET_SLACK_BOT_TOKEN env var documentation.
+
+## Key Files to Modify
+1. `socketsecurity/plugins/slack.py` - main implementation
+2. `README.md` - add bot mode documentation
+
+## Notes
+- Slack chat.postMessage returns HTTP 200 even on errors. Check response JSON for `"ok": false`
+- Rate limit: 1 message per second per channel (more generous than webhooks)
+- Channel names are case-insensitive, don't need # prefix
+- Public and private channels both work if bot is invited

{socketsecurity-2.2.59 → socketsecurity-2.2.62}/socketsecurity/__init__.py

@@ -1,3 +1,3 @@
 __author__ = 'socket.dev'
-__version__ = '2.2.59'
+__version__ = '2.2.62'
 USER_AGENT = f'SocketPythonCLI/{__version__}'

{socketsecurity-2.2.59 → socketsecurity-2.2.62}/socketsecurity/config.py

@@ -57,6 +57,7 @@ class CliConfig:
     version: str = __version__
     jira_plugin: PluginConfig = field(default_factory=PluginConfig)
     slack_plugin: PluginConfig = field(default_factory=PluginConfig)
+    slack_webhook: Optional[str] = None
     license_file_name: str = "license_output.json"
     save_submitted_files_list: Optional[str] = None
     save_manifest_tar: Optional[str] = None
@@ -85,8 +86,14 @@ class CliConfig:
         parser = create_argument_parser()
         args = parser.parse_args(args_list)
 
-        # Get API token from env or args
-        api_token = os.getenv("SOCKET_SECURITY_API_KEY") or args.api_token
+        # Get API token from env or args (check multiple env var names)
+        api_token = (
+            os.getenv("SOCKET_SECURITY_API_KEY") or
+            os.getenv("SOCKET_SECURITY_API_TOKEN") or
+            os.getenv("SOCKET_API_KEY") or
+            os.getenv("SOCKET_API_TOKEN") or
+            args.api_token
+        )
 
         # Strip quotes from commit message if present
         commit_message = args.commit_message
@@ -128,6 +135,7 @@ class CliConfig:
             'save_manifest_tar': args.save_manifest_tar,
             'sub_paths': args.sub_paths or [],
             'workspace_name': args.workspace_name,
+            'slack_webhook': args.slack_webhook,
             'reach': args.reach,
             'reach_version': args.reach_version,
             'reach_analysis_timeout': args.reach_analysis_timeout,
@@ -151,6 +159,11 @@ class CliConfig:
         except json.JSONDecodeError:
             logging.error(f"Unable to parse excluded_ecosystems: {config_args['excluded_ecosystems']}")
             exit(1)
+        # Build Slack plugin config, merging CLI arg with env config
+        slack_config = get_plugin_config_from_env("SOCKET_SLACK")
+        if args.slack_webhook:
+            slack_config["url"] = args.slack_webhook
+            
         config_args.update({
             "jira_plugin": PluginConfig(
                 enabled=os.getenv("SOCKET_JIRA_ENABLED", "false").lower() == "true",
@@ -158,9 +171,9 @@ class CliConfig:
                 config=get_plugin_config_from_env("SOCKET_JIRA")
             ),
             "slack_plugin": PluginConfig(
-                enabled=os.getenv("SOCKET_SLACK_ENABLED", "false").lower() == "true",
+                enabled=bool(slack_config) or bool(args.slack_webhook),
                 levels=os.getenv("SOCKET_SLACK_LEVELS", "block,warn").split(","),
-                config=get_plugin_config_from_env("SOCKET_SLACK")
+                config=slack_config
             )
         })
 
@@ -212,7 +225,7 @@ def create_argument_parser() -> argparse.ArgumentParser:
         "--api-token",
         dest="api_token",
         metavar="<token>",
-        help="Socket Security API token (can also be set via SOCKET_SECURITY_API_KEY env var)",
+        help="Socket Security API token (can also be set via SOCKET_SECURITY_API_TOKEN env var)",
         required=False
     )
     auth_group.add_argument(
@@ -475,6 +488,15 @@ def create_argument_parser() -> argparse.ArgumentParser:
         help=argparse.SUPPRESS
     )
 
+    # Plugin Configuration
+    plugin_group = parser.add_argument_group('Plugin Configuration')
+    plugin_group.add_argument(
+        "--slack-webhook",
+        dest="slack_webhook",
+        metavar="<url>",
+        help="Slack webhook URL for notifications (automatically enables Slack plugin)"
+    )
+
     # Advanced Configuration
     advanced_group = parser.add_argument_group('Advanced Configuration')
     advanced_group.add_argument(

{socketsecurity-2.2.59 → socketsecurity-2.2.62}/socketsecurity/core/__init__.py

@@ -553,7 +553,10 @@ class Core:
 
         # Finalize tier1 scan if reachability analysis was enabled
         if self.cli_config and self.cli_config.reach:
-            facts_file_path = self.cli_config.reach_output_file or ".socket.facts.json"
+            facts_file_path = os.path.join(
+                self.cli_config.target_path or ".", 
+                self.cli_config.reach_output_file
+            )
             log.debug(f"Reachability analysis enabled, finalizing tier1 scan for full scan {full_scan.id}")
             try:
                 success = self.finalize_tier1_scan(full_scan.id, facts_file_path)