Skip to content

Commit 3244e7c

Browse files
mtorpmtorp
committed
docs: align reachability reference with v2.4.2 implementation
Bring docs/cli-reference.md in line with the v2.4.2 reachability flag alignment (#226): canonical --reach-analysis-timeout / --reach-analysis-memory-limit names (old names noted as hidden aliases), correct coana-derived defaults (8 GB memory, 10-min timeout, concurrency 1), accurate --reach-min-severity values (info/low/moderate/high/critical), the uv + Enterprise-plan requirements, the new 2.4.x reachability flags, and clearer --only-facts-file wording. Documentation-only; the patch bump to 2.4.3 + uv.lock refresh are mandated by the repo's sync-version pre-commit hook.
1 parent 7d7ac0c commit 3244e7c

5 files changed

Lines changed: 50 additions & 23 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,19 @@
11
# Changelog
22

3+
## 2.4.3
4+
5+
### Docs: reachability CLI reference aligned with the v2.4.2 implementation
6+
7+
- `docs/cli-reference.md` now uses the canonical `--reach-analysis-timeout` /
8+
`--reach-analysis-memory-limit` flag names (old `--reach-timeout` /
9+
`--reach-memory-limit` documented as hidden aliases), the correct
10+
coana-derived defaults (8 GB memory, 10-min timeout, concurrency 1), the
11+
accurate `--reach-min-severity` values (info/low/moderate/high/critical),
12+
the `uv` and Enterprise-plan requirements, and the newer reachability flags
13+
(`--reach-enable-analysis-splitting`, `--reach-detailed-analysis-log-file`,
14+
`--reach-lazy-mode`, `--reach-use-only-pregenerated-sboms`, `--reach-debug`,
15+
`--reach-disable-external-tool-checks`). Documentation-only; no code changes.
16+
317
## 2.4.2
418

519
### Added: reachability flag and Coana environment alignment with the Node CLI

‎docs/cli-reference.md‎

Lines changed: 33 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -152,10 +152,11 @@ socketcli [-h] [--api-token API_TOKEN] [--repo REPO] [--workspace WORKSPACE] [--
152152
[--enable-json] [--enable-sarif] [--sarif-file <path>] [--sarif-scope {diff,full}] [--sarif-grouping {instance,alert}] [--sarif-reachability {all,reachable,potentially,reachable-or-potentially}] [--enable-gitlab-security] [--gitlab-security-file <path>]
153153
[--disable-overview] [--exclude-license-details] [--allow-unverified] [--disable-security-issue]
154154
[--ignore-commit-files] [--disable-blocking] [--disable-ignore] [--enable-diff] [--scm SCM] [--timeout TIMEOUT] [--include-module-folders]
155-
[--reach] [--reach-version REACH_VERSION] [--reach-timeout REACH_ANALYSIS_TIMEOUT]
156-
[--reach-memory-limit REACH_ANALYSIS_MEMORY_LIMIT] [--reach-ecosystems REACH_ECOSYSTEMS] [--reach-exclude-paths REACH_EXCLUDE_PATHS]
157-
[--reach-min-severity {low,medium,high,critical}] [--reach-skip-cache] [--reach-disable-analytics] [--reach-output-file REACH_OUTPUT_FILE]
158-
[--only-facts-file] [--version]
155+
[--reach] [--reach-version REACH_VERSION] [--reach-analysis-timeout SECONDS] [--reach-analysis-memory-limit MB]
156+
[--reach-concurrency N] [--reach-ecosystems REACH_ECOSYSTEMS] [--reach-exclude-paths REACH_EXCLUDE_PATHS]
157+
[--reach-min-severity <level>] [--reach-skip-cache] [--reach-disable-analytics] [--reach-enable-analysis-splitting]
158+
[--reach-detailed-analysis-log-file] [--reach-lazy-mode] [--reach-output-file REACH_OUTPUT_FILE] [--reach-additional-params ...]
159+
[--reach-use-only-pregenerated-sboms] [--reach-debug] [--reach-disable-external-tool-checks] [--only-facts-file] [--version]
159160
````
160161

161162
If you don't want to provide the Socket API Token every time then you can use the environment variable `SOCKET_SECURITY_API_TOKEN`
@@ -237,23 +238,35 @@ If you don't want to provide the Socket API Token every time then you can use th
237238
#### Reachability Analysis
238239
| Parameter | Required | Default | Description |
239240
|:---------------------------------|:---------|:--------|:---------------------------------------------------------------------------------------------------------------------------|
240-
| `--reach` | False | False | Enable reachability analysis to identify which vulnerable functions are actually called by your code |
241-
| `--reach-version` | False | latest | Version of @coana-tech/cli to use for analysis |
242-
| `--reach-timeout` | False | 1200 | Timeout in seconds for the reachability analysis (default: 1200 seconds / 20 minutes) |
243-
| `--reach-memory-limit` | False | 4096 | Memory limit in MB for the reachability analysis (default: 4096 MB / 4 GB) |
244-
| `--reach-concurrency` | False | | Control parallel analysis execution (must be >= 1) |
245-
| `--reach-additional-params` | False | | Pass custom parameters to the coana CLI tool |
246-
| `--reach-ecosystems` | False | | Comma-separated list of ecosystems to analyze (e.g., "npm,pypi"). If not specified, all supported ecosystems are analyzed |
247-
| `--reach-exclude-paths` | False | | Comma-separated list of file paths or patterns to exclude from reachability analysis |
248-
| `--reach-min-severity` | False | | Minimum severity level for reporting reachability results (low, medium, high, critical) |
249-
| `--reach-skip-cache` | False | False | Skip cache and force fresh reachability analysis |
250-
| `--reach-disable-analytics` | False | False | Disable analytics collection during reachability analysis |
251-
| `--reach-output-file` | False | .socket.facts.json | Path where reachability analysis results should be saved |
252-
| `--only-facts-file` | False | False | Submit only the .socket.facts.json file to an existing scan (requires --reach and a prior scan) |
241+
| `--reach` | False | False | Enable reachability analysis to identify which vulnerable functions are actually called by your code. Creates a tier-1 full-application reachability scan (`scan_type=socket_tier1`). |
242+
| `--reach-version` | False | latest | Version of @coana-tech/cli to use for analysis |
243+
| `--reach-analysis-timeout` | False | *coana default (10 min)* | Timeout in seconds for the reachability analysis. When unset, the coana CLI's own default applies. Alias: `--reach-timeout` (hidden). |
244+
| `--reach-analysis-memory-limit` | False | *coana default (8192 MB / 8 GB)* | Memory limit in MB for the reachability analysis. When unset, the coana CLI's own default applies. Alias: `--reach-memory-limit` (hidden). |
245+
| `--reach-concurrency` | False | *coana default (1)* | Number of analyses to run in parallel (must be >= 1). Useful for monorepos/workspaces. |
246+
| `--reach-additional-params` | False | | Pass custom parameters straight through to the coana CLI tool |
247+
| `--reach-ecosystems` | False | *all* | Comma-separated list of ecosystems to analyze (e.g., "npm,pypi"). If not specified, all supported ecosystems are analyzed |
248+
| `--reach-exclude-paths` | False | | Comma-separated list of file paths or patterns to exclude from reachability analysis |
249+
| `--reach-min-severity` | False | | Minimum severity level for reporting reachability results (info, low, moderate, high, critical) |
250+
| `--reach-skip-cache` | False | False | Skip cache and force fresh reachability analysis |
251+
| `--reach-disable-analytics` | False | False | Disable analytics collection during reachability analysis |
252+
| `--reach-enable-analysis-splitting` | False | False | Enable analysis splitting/bucketing (a legacy performance feature). Splitting is disabled by default. |
253+
| `--reach-detailed-analysis-log-file` | False | False | Write a detailed analysis log file; its path is printed to stdout |
254+
| `--reach-lazy-mode` | False | False | Enable lazy mode (experimental performance feature) |
255+
| `--reach-output-file` | False | .socket.facts.json | Path where reachability analysis results should be saved |
256+
| `--reach-use-only-pregenerated-sboms`| False | False | Build the scan only from pre-generated CycloneDX (CDX) and SPDX files in your project (requires --reach) |
257+
| `--reach-debug` | False | False | Enable coana debug output (passes `--debug` to the coana CLI), independent of the global `--enable-debug` |
258+
| `--reach-disable-external-tool-checks`| False | False | Disable coana's external tool availability checks (passes `--disable-external-tool-checks` to the coana CLI) |
259+
| `--only-facts-file` | False | False | Submit only the .socket.facts.json file when creating the full scan (requires --reach) |
253260
254261
**Reachability Analysis Requirements:**
255-
- `npm` - Required to install and run @coana-tech/cli
256-
- `npx` - Required to execute @coana-tech/cli
262+
263+
The Python CLI verifies the following **up front** (before invoking the analysis engine) and exits with code **3** if any are unmet:
264+
- `npm` - Required to install and run `@coana-tech/cli` (the analysis engine)
265+
- `npx` - Required to execute `@coana-tech/cli`
266+
- `uv` - Required by the analysis engine
267+
- An **Enterprise** Socket organization plan (any `enterprise*` plan, including Enterprise trials)
268+
269+
Separately, the analysis engine (coana) needs the **per-ecosystem build toolchain** for whatever languages your project uses — e.g. a compatible Python interpreter (3.11+, or PyPy) for Python, a JDK for Java/Kotlin/Scala, .NET 6+ for C#, the matching Go toolchain for Go, etc. These are validated by the engine **at analysis time** (the CLI does not pre-check them) and that validation can be skipped with `--reach-disable-external-tool-checks`.
257270
258271
## Config file support
259272
@@ -299,7 +312,7 @@ Sample config files:
299312
300313
For CI-specific examples and guidance, see [`ci-cd.md`](ci-cd.md).
301314
302-
The CLI will automatically install `@coana-tech/cli` if not present. Use `--reach` to enable reachability analysis during a full scan, or use `--only-facts-file` with `--reach` to submit reachability results to an existing scan.
315+
The CLI will automatically install `@coana-tech/cli` if not present. Use `--reach` to enable reachability analysis during a full scan, or add `--only-facts-file` (with `--reach`) to submit only the reachability facts file (`.socket.facts.json`) when creating the full scan.
303316
304317
#### Advanced Configuration
305318
| Parameter | Required | Default | Description |

‎pyproject.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
66

77
[project]
88
name = "socketsecurity"
9-
version = "2.4.2"
9+
version = "2.4.3"
1010
requires-python = ">= 3.11"
1111
license = {"file" = "LICENSE"}
1212
dependencies = [

‎socketsecurity/__init__.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
__author__ = 'socket.dev'
2-
__version__ = '2.4.2'
2+
__version__ = '2.4.3'
33
USER_AGENT = f'SocketPythonCLI/{__version__}'

‎uv.lock‎

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)