No description
  • Go 76.3%
  • Shell 18.3%
  • Dockerfile 2.7%
  • Makefile 2.7%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-16 18:55:36 -03:00
internal scan: set mode 0600 on a configuration file that exists 2026-11-16 16:07:32 -03:00
testlab testlab: update Alpine to 3.24 and Pocket ID to 2.19.3 2026-11-16 18:48:12 -03:00
.dockerignore container: add image and docker targets 2026-10-19 10:22:19 -03:00
.gitignore treewide: initial import of the shellgraph collector 2026-10-17 20:35:57 -03:00
.version version: bump to 1.1.2 2026-11-16 18:55:36 -03:00
CLAUDE.md collect: limit the script output to 64 MiB 2026-11-16 16:07:32 -03:00
default.pgo treewide: initial import of the shellgraph collector 2026-10-17 20:35:57 -03:00
Dockerfile Dockerfile: pin the base image by digest 2026-11-16 18:28:42 -03:00
go.mod go.mod: update Go to 1.27.4 and update the modules 2026-11-16 18:43:56 -03:00
go.sum go.mod: update Go to 1.27.4 and update the modules 2026-11-16 18:43:56 -03:00
main.go main: let login read the token from SHELLGRAPH_TOKEN 2026-11-16 16:07:44 -03:00
Makefile container: add image and docker targets 2026-10-19 10:22:19 -03:00
README.md readme: explain macOS quarantine attribute of downloaded binaries 2026-10-23 08:54:53 -03:00

shellgraph (collector)

The ShellGraph collector. It scans one VLAN with SSH, finds the services and their connections on each host, and sends one report to shellgraph-server. It installs nothing on the target hosts.

Quick start

make build-local
./bin/shellgraph login --server https://shellgraph.example.net --token <token>
./bin/shellgraph scan

macOS

macOS puts a quarantine attribute on a binary that you download. Then macOS blocks the first run. Remove the attribute before you run the collector:

xattr -d com.apple.quarantine shellgraph-darwin-arm64

On an Intel Mac, use shellgraph-darwin-amd64. A binary that you build with make build-local does not have this attribute.

Scan finds too few hosts

The collector connects to 32 addresses at the same time. A firewall or an IPS can see this as a port scan and drop the packets. Then most addresses get the status no_ssh, and the server removes those hosts from the VLAN.

Addresses with no_ssh have no line in the output. Read the Done: line. If a large VLAN shows too few hosts, run the scan again with a lower concurrency and --dry-run:

./bin/shellgraph scan --env Production --vlan app-10 --concurrency 4 --dry-run > /dev/null

If the number of hosts increases, use the lower concurrency for this VLAN. See "Scan a large VLAN" in content/docs/collector/how-to/run-scan.md in the site repository.

Development

  • make test: Go tests.
  • make build: binaries for Linux and macOS, amd64 and arm64.
  • make image: container image shellgraph:<version> (FROM scratch). make docker: push it to git.rda.run/shellgraph/collector.
  • testlab/lab.sh e2e: end-to-end test with Podman (see testlab/README.md).
  • make help: all targets.

Documentation: the site repository, section /docs/collector/ (content/docs/collector/).