Skip to content

Commit 464549a

Browse files
lelialelia
committed
Refactor docs to reduce README complexity, create dedicated CLI and CI/CD guides
Signed-off-by: lelia <lelia@socket.dev>
1 parent 1b82588 commit 464549a

7 files changed

Lines changed: 1076 additions & 835 deletions

File tree

‎README.md‎

Lines changed: 93 additions & 825 deletions
Large diffs are not rendered by default.

‎docs/README.md‎

Lines changed: 0 additions & 10 deletions
This file was deleted.

‎docs/ci-cd.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# CI/CD guide
2+
3+
Use this guide for pipeline-focused CLI usage across platforms.
4+
5+
## Recommended patterns
6+
7+
### Dashboard-style reachable SARIF
8+
9+
```bash
10+
socketcli \
11+
--reach \
12+
--sarif-file results.sarif \
13+
--sarif-scope full \
14+
--sarif-grouping alert \
15+
--sarif-reachability reachable \
16+
--disable-blocking
17+
```
18+
19+
### Diff-based gating on new reachable findings
20+
21+
```bash
22+
socketcli \
23+
--reach \
24+
--sarif-file results.sarif \
25+
--sarif-scope diff \
26+
--sarif-reachability reachable \
27+
--strict-blocking
28+
```
29+
30+
## Config file usage in CI
31+
32+
Use `--config .socketcli.toml` to keep pipeline commands small.
33+
34+
Precedence order:
35+
36+
`CLI flags` > `environment variables` > `config file` > `built-in defaults`
37+
38+
Example:
39+
40+
```toml
41+
[socketcli]
42+
reach = true
43+
sarif_scope = "full"
44+
sarif_grouping = "alert"
45+
sarif_reachability = "reachable"
46+
sarif_file = "results.sarif"
47+
```
48+
49+
## Platform examples
50+
51+
### GitHub Actions
52+
53+
```yaml
54+
- name: Run Socket CLI
55+
run: socketcli --config .socketcli.toml --target-path .
56+
env:
57+
SOCKET_SECURITY_API_TOKEN: ${{ secrets.SOCKET_SECURITY_API_TOKEN }}
58+
```
59+
60+
### Buildkite
61+
62+
```yaml
63+
steps:
64+
- label: "Socket scan"
65+
command: "socketcli --config .socketcli.toml --target-path ."
66+
env:
67+
SOCKET_SECURITY_API_TOKEN: "${SOCKET_SECURITY_API_TOKEN}"
68+
```
69+
70+
### GitLab CI
71+
72+
```yaml
73+
socket_scan:
74+
script:
75+
- socketcli --config .socketcli.toml --target-path .
76+
variables:
77+
SOCKET_SECURITY_API_TOKEN: $SOCKET_SECURITY_API_TOKEN
78+
```
79+
80+
### Bitbucket Pipelines
81+
82+
```yaml
83+
pipelines:
84+
default:
85+
- step:
86+
script:
87+
- socketcli --config .socketcli.toml --target-path .
88+
```
89+
90+
## Workflow templates
91+
92+
Prebuilt examples in this repo:
93+
94+
- [`../workflows/github-actions.yml`](../workflows/github-actions.yml)
95+
- [`../workflows/buildkite.yml`](../workflows/buildkite.yml)
96+
- [`../workflows/gitlab-ci.yml`](../workflows/gitlab-ci.yml)
97+
- [`../workflows/bitbucket-pipelines.yml`](../workflows/bitbucket-pipelines.yml)
98+
99+
## CI gotchas
100+
101+
- `--strict-blocking` changes pass/fail policy, not SARIF dataset semantics.
102+
- `--sarif-scope full` requires `--reach`.
103+
- `--sarif-grouping alert` currently applies to `--sarif-scope full`.
104+
- Diff-based SARIF can validly be empty when there are no matching net-new alerts.
105+
- Keep API tokens in secret stores (`SOCKET_SECURITY_API_TOKEN`), not in config files.

‎docs/cli-reference.md‎

Lines changed: 712 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/development.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
# Development guide
2+
3+
## Local setup
4+
5+
This project uses `pyproject.toml` and `uv.lock` for dependency management.
6+
7+
### Standard setup (PyPI dependencies)
8+
9+
```bash
10+
pyenv local 3.11
11+
make first-time-setup
12+
```
13+
14+
### Local SDK development setup
15+
16+
```bash
17+
pyenv local 3.11
18+
SOCKET_SDK_PATH=~/path/to/socketdev make first-time-local-setup
19+
```
20+
21+
Default local SDK path is `../socketdev` when `SOCKET_SDK_PATH` is not set.
22+
23+
## Ongoing workflows
24+
25+
After dependency changes:
26+
27+
```bash
28+
make update-deps
29+
```
30+
31+
After pulling latest changes:
32+
33+
```bash
34+
make sync-all
35+
```
36+
37+
Run tests:
38+
39+
```bash
40+
make test
41+
```
42+
43+
Run lint/format checks:
44+
45+
```bash
46+
make lint
47+
```
48+
49+
## Make targets
50+
51+
High-level:
52+
53+
- `make first-time-setup`
54+
- `make first-time-local-setup`
55+
- `make update-lock`
56+
- `make sync-all`
57+
- `make dev-setup`
58+
59+
Implementation:
60+
61+
- `make local-dev`
62+
- `make setup`
63+
- `make sync`
64+
- `make clean`
65+
- `make test`
66+
- `make lint`
67+
68+
## Environment variables
69+
70+
Core:
71+
72+
- `SOCKET_SECURITY_API_TOKEN` (also supports `SOCKET_SECURITY_API_KEY`, `SOCKET_API_KEY`, `SOCKET_API_TOKEN`)
73+
- `SOCKET_SDK_PATH` (default `../socketdev`)
74+
75+
GitLab:
76+
77+
- `GITLAB_TOKEN`
78+
- `CI_JOB_TOKEN`
79+
80+
## Manual setup (without `make`)
81+
82+
```bash
83+
python -m venv .venv
84+
source .venv/bin/activate
85+
uv sync
86+
uv add --dev pre-commit
87+
pre-commit install
88+
```
89+
90+
## Related docs
91+
92+
- CLI quick start: [`../README.md`](../README.md)
93+
- CI/CD usage: [`ci-cd.md`](ci-cd.md)
94+
- Full CLI reference: [`cli-reference.md`](cli-reference.md)
95+
- Troubleshooting: [`troubleshooting.md`](troubleshooting.md)

‎docs/troubleshooting.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Troubleshooting
2+
3+
## Common gotchas
4+
5+
- `--strict-blocking` changes pass/fail policy, not SARIF dataset source.
6+
- `--sarif-scope full` requires `--reach`.
7+
- In `--sarif-scope full` with `--sarif-file`, SARIF JSON is written to file and stdout JSON is suppressed.
8+
- `--sarif-grouping alert` currently applies to `--sarif-scope full`.
9+
10+
## Save submitted file list
11+
12+
Use `--save-submitted-files-list` to inspect exactly what was sent for scanning.
13+
14+
```bash
15+
socketcli --save-submitted-files-list submitted_files.json
16+
```
17+
18+
Output includes:
19+
20+
- timestamp
21+
- total file count
22+
- total size
23+
- complete submitted file list
24+
25+
## Save manifest archive
26+
27+
Use `--save-manifest-tar` to export discovered manifest files as `.tar.gz`.
28+
29+
```bash
30+
socketcli --save-manifest-tar manifest_files.tar.gz
31+
```
32+
33+
Combined example:
34+
35+
```bash
36+
socketcli --save-submitted-files-list files.json --save-manifest-tar backup.tar.gz
37+
```
38+
39+
## Octopus merge note
40+
41+
For octopus merges (3+ parents), Git can report incomplete changed-file sets because default diff compares against the first parent.
42+
43+
If needed, force full scan behavior with:
44+
45+
- `--ignore-commit-files`
46+
47+
## GitLab report troubleshooting
48+
49+
If report is not visible in GitLab Security Dashboard:
50+
51+
- verify `dependency_scanning` artifact is configured in `.gitlab-ci.yml`
52+
- verify job completed and artifact uploaded
53+
- verify report file schema is valid
54+
55+
If vulnerabilities array is empty:
56+
57+
- this can be expected when no actionable security issues are present in the result scope
58+
- confirm expected scope/flags and compare with Socket dashboard data

‎workflows/buildkite.yml‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Socket Security Buildkite pipeline example
2+
# Runs Socket CLI in a Buildkite step using repository-level environment variables.
3+
4+
steps:
5+
- label: "Socket Security Scan"
6+
command: |
7+
socketcli \
8+
--target-path . \
9+
--scm api \
10+
--pr-number 0
11+
env:
12+
# Configure this in Buildkite pipeline/repo settings.
13+
SOCKET_SECURITY_API_TOKEN: "${SOCKET_SECURITY_API_TOKEN}"

0 commit comments

Comments
 (0)