dev-machine-guard MCP server

Why Dev Machine Guard?

Developer machines are the new attack surface. They hold high-value assets — GitHub tokens, cloud credentials, SSH keys — and routinely execute untrusted code through dependencies and AI-powered tools. Recent supply chain attacks have shown that malicious VS Code extensions can steal credentials, rogue MCP servers can access your codebase, and compromised npm packages can exfiltrate secrets.

EDR and traditional MDM solutions monitor device posture and compliance, but they have zero visibility into the developer tooling layer:

Capability	EDR / MDM	Dev Machine Guard
IDE extension audit		Yes
AI agent & tool inventory		Yes
MCP server config audit		Yes
Package scanning (Node.js, Homebrew, Python, system)		Yes
Package-manager config audit (registry, cooldown, auth)		Yes
Suspicious file / IOC detection		Yes
Cross-platform (macOS, Windows, Linux)	Yes	Yes
Device posture & compliance	Yes
Malware / virus detection	Yes

Dev Machine Guard is complementary to EDR/MDM — not a replacement. Deploy it alongside your existing tools via MDM (Jamf, Kandji, Intune) or run it standalone.

Quick Start

The steps below install the binary directly and are intended for community users evaluating Dev Machine Guard on a single machine.

Enterprise customers should not install the binary manually. Deploy Dev Machine Guard across your fleet using the loader script through your MDM or EDR tooling. See the Installation Script documentation for the supported, auto-updating deployment flow.

Install from release (community)

Download the latest binary for your platform from GitHub Releases. Release asset filenames embed the version (for example, stepsecurity-dev-machine-guard-1.19.1-darwin), so the snippets below resolve the latest tag first rather than hardcoding a version.

macOS (universal binary — Apple Silicon and Intel)

VERSION=$(curl -fsSL https://api.github.com/repos/step-security/dev-machine-guard/releases/latest | grep '"tag_name"' | cut -d'"' -f4 | sed 's/^v//')
curl -fsSL "https://github.com/step-security/dev-machine-guard/releases/download/v${VERSION}/stepsecurity-dev-machine-guard-${VERSION}-darwin" -o stepsecurity-dev-machine-guard
chmod +x stepsecurity-dev-machine-guard

# Run the scan
./stepsecurity-dev-machine-guard

Windows (PowerShell)

$version = (Invoke-RestMethod https://api.github.com/repos/step-security/dev-machine-guard/releases/latest).tag_name.TrimStart('v')
$arch = if ($env:PROCESSOR_ARCHITECTURE -eq 'ARM64') { 'arm64' } else { 'amd64' }
Invoke-WebRequest -Uri "https://github.com/step-security/dev-machine-guard/releases/download/v$version/stepsecurity-dev-machine-guard-$version-windows_$arch.exe" -OutFile "stepsecurity-dev-machine-guard.exe"

# Run the scan
.\stepsecurity-dev-machine-guard.exe

Linux

VERSION=$(curl -fsSL https://api.github.com/repos/step-security/dev-machine-guard/releases/latest | grep '"tag_name"' | cut -d'"' -f4 | sed 's/^v//')
ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
curl -fsSL "https://github.com/step-security/dev-machine-guard/releases/download/v${VERSION}/stepsecurity-dev-machine-guard-${VERSION}-linux_${ARCH}" -o stepsecurity-dev-machine-guard
chmod +x stepsecurity-dev-machine-guard

# Run the scan
./stepsecurity-dev-machine-guard

Pre-built .deb and .rpm packages are also available on the releases page.

Build from source

git clone https://github.com/step-security/dev-machine-guard.git
cd dev-machine-guard
make build
./stepsecurity-dev-machine-guard

Requires Go 1.26+. The binary has zero external dependencies.

Usage

stepsecurity-dev-machine-guard [COMMAND] [OPTIONS]

Commands

Command	Description
(none)	Run a scan (community mode, pretty output)
configure	Interactively set all settings (enterprise, scan, output)
configure show	Show current configuration (API key masked)
install	Install scheduled scanning — launchd (macOS), systemd (Linux), schtasks (Windows)
uninstall	Remove scheduled scanning configuration
send-telemetry	Upload scan results to the StepSecurity dashboard (enterprise)

Output Formats

Flag	Description
--pretty	Pretty terminal output (default)
--json	JSON output to stdout
--html FILE	Self-contained HTML report saved to FILE

Options

Flag	Description
--search-dirs DIR [DIR...]	Search DIRs instead of $HOME (replaces default; repeatable)
--enable-npm-scan	Enable Node.js package scanning
--disable-npm-scan	Disable Node.js package scanning
--enable-brew-scan	Enable Homebrew package scanning
--disable-brew-scan	Disable Homebrew package scanning
--enable-python-scan	Enable Python package scanning
--disable-python-scan	Disable Python package scanning
--include-bundled-plugins	Include bundled/platform IDE plugins in output
--log-level=LEVEL	Log level: error | warn | info | debug
--verbose	Shortcut for --log-level=debug
--force-scan	Scan now regardless of the dashboard cadence; still checks in
--color=WHEN	Color mode: auto | always | never (default: auto)
-v, --version	Show version
-h, --help	Show help

Examples

# Pretty terminal output (default)
./stepsecurity-dev-machine-guard

# JSON output
./stepsecurity-dev-machine-guard --json
./stepsecurity-dev-machine-guard --json | python3 -m json.tool   # formatted
./stepsecurity-dev-machine-guard --json > scan.json               # to file

# HTML report
./stepsecurity-dev-machine-guard --html report.html

# Verbose scan with npm packages — shows progress spinners and timing
./stepsecurity-dev-machine-guard --verbose --enable-npm-scan

# Scan specific directories instead of $HOME
./stepsecurity-dev-machine-guard --search-dirs /Volumes/code
./stepsecurity-dev-machine-guard --search-dirs /tmp /opt          # multiple dirs

# Pipe JSON through jq to extract just AI tools
./stepsecurity-dev-machine-guard --json | jq '.ai_agents_and_tools'

# Count IDE extensions
./stepsecurity-dev-machine-guard --json | jq '.summary.ide_extensions_count'

# Check for MCP configs (exit 1 if any found — useful in CI)
count=$(./stepsecurity-dev-machine-guard --json | jq '.summary.mcp_configs_count')
[ "$count" -gt 0 ] && echo "MCP servers detected!" && exit 1

# Disable colors for piping or logging
./stepsecurity-dev-machine-guard --color=never 2>&1 | tee scan.log

# Enterprise: configure all settings interactively
./stepsecurity-dev-machine-guard configure

# Enterprise: view saved configuration (API key masked)
./stepsecurity-dev-machine-guard configure show

# Enterprise: install scheduled scanning (launchd / systemd / schtasks)
./stepsecurity-dev-machine-guard install

# Enterprise: one-time telemetry upload
./stepsecurity-dev-machine-guard send-telemetry

# Enterprise: scan even when the dashboard-managed scan cadence says "not due"
# (equivalent env var: STEPSEC_FORCE_SCAN=1; disable gating: STEPSEC_DISABLE_RUN_GATE=1)
./stepsecurity-dev-machine-guard send-telemetry --force-scan

# Enterprise: remove scheduled scanning
./stepsecurity-dev-machine-guard uninstall

Configuration

Run configure to set up enterprise credentials and default search directories:

./stepsecurity-dev-machine-guard configure

This interactively prompts for all configurable settings:

Setting	Description	Default
Device ID	Optional custom identifier for this device	Machine serial
Customer ID	Your StepSecurity customer identifier	(not set)
API Endpoint	StepSecurity backend URL	(not set)
API Key	Authentication key for telemetry uploads	(not set)
Scan Frequency	How often scheduled scans run (hours)	(not set)
Search Directories	Comma-separated list of directories to scan	$HOME
Enable NPM Scan	Node.js package scanning	auto
Enable Brew Scan	Homebrew package scanning	auto
Enable Python Scan	Python package scanning	auto
Color Mode	Terminal color output	auto
Output Format	Default output format	pretty
HTML Output File	Default path for HTML reports	(not set)
Log Level	Logging verbosity	error

On an ephemeral device with no detected user identity (empty, unknown, or root), assign one once:

./stepsecurity-dev-machine-guard configure --non-interactive --user-id employee-123

This does not require enterprise credentials. The ID uses 1–256 ASCII letters, digits, or @ . _ + -; surrounding whitespace is trimmed, control characters are rejected, and unknown/root are reserved regardless of case. An ID-only JSON import such as {"user_id":"employee-123"} also works through configure --from-file PATH.

An existing detected email or regular OS username prevents assignment. Once assigned, scans and hooks use the stored ID even if automatic detection changes. Repeating the same value succeeds; replacing or clearing it fails without changing configuration. Other configure operations preserve it. The guarantee applies to the existing configuration scope; the config file owner can still edit or remove files directly. Provision after cloning an ephemeral image to avoid copying an assigned identity to every clone.

When no user identity is available, scanning continues as unknown with a warning and remains eligible for later assignment. Enterprise telemetry includes explicit user_id_missing and device_id_missing booleans based on the resolved identities, including false values. OS login state (no_user_logged_in) is detected independently of attribution. Backend handling of missing device IDs requires deployment verification.

View current settings:

./stepsecurity-dev-machine-guard configure show

Configuration (~/.stepsecurity/config.json):

  Customer ID:             my-company
  API Endpoint:            https://api.stepsecurity.io
  API Key:                 ***a1b2
  Scan Frequency:          4 hours
  Search Directories:      $HOME, /Volumes/code
  Enable NPM Scan:         auto
  Enable Brew Scan:        auto
  Enable Python Scan:      auto
  Color Mode:              auto
  Output Format:           pretty
  Log Level:               error

Configuration is saved to ~/.stepsecurity/config.json with 0600 permissions (owner read/write only).

To label a device for the dashboard, add "device_tag": "avd-pool-eu" to the config JSON, pass configure --device-tag avd-pool-eu, or use the MSI DEVICETAG property. The tag is set in the agent configuration only (the dashboard shows it and never edits it). In the dashboard's Device activity settings an admin can limit retirement (on uninstall, by inactivity and from the dashboard) to devices carrying chosen tags; the default applies it to all devices.

To use a custom device ID, add "device_id": "my-device-123" to the existing config JSON, set Device ID through configure, or pass configure --device-id my-device-123. The override is also supported in JSON supplied to configure --from-file. A literal device ID must follow the ID format above; empty or whitespace-only inputs are rejected. An absent saved override uses the machine serial as before. To reset an existing override, enter - at the interactive Device ID prompt or pass --device-id -. The agent continues reporting the actual machine serial in serial_number. WSL guest scans derive separate IDs from the host ID and distro ID.

Choose an ID unique within your customer and keep it stable: changing the ID registers a separate device in the backend; it does not migrate existing history.

The value may also be a template over {serial} and {hostname} (for example {hostname} on pooled virtual desktops rebuilt under stable names, so a rebuilt host keeps its device and history), and the STEPSEC_DEVICE_ID environment variable overrides it at run time. A device is always the machine: on a shared Windows host (a multi-session edition or the RD Session Host role; with multi_user_detection: users, also one where two developers have each scanned on two different days) every signed-in session runs its own scan and reports under the same device with its own user_identity and user_token, and the dashboard lists the users inside the device; multi_user_detection: off keeps one scan per tick. identity --json prints the identity a machine reports under. Every scan also reports whether the machine is virtual or physical and on which hypervisor or cloud. See docs/deploying-on-virtual-desktops.md.

Every setting can also be written without prompts, which is how MDM, MSI and CI deployments configure the agent. Any setting flag passed to configure selects the no-prompt path; settings you don't pass keep their current value. Credentials are required only when the command sets one of them, passes --from-file, or sets nothing at all, so a community install can change preferences (configure --color=never) without them:

./stepsecurity-dev-machine-guard configure --non-interactive \
  --customer-id my-company --api-endpoint https://api.stepsecurity.io \
  --device-id my-device-123 --scan-frequency 4 --search-dirs /Volumes/code \
  --disable-brew-scan --log-level=info

Setting	configure flag
User ID (one-time)	--user-id ID (only when no usable identity is detected)
Device ID	--device-id VALUE (a literal, or a template over {serial} {hostname}; - clears)
Device tag	--device-tag TAG (- clears)
Retire on uninstall	--retire-on-uninstall[=BOOL]
Multi-user detection	--multi-user-detection MODE (edition, users, off; - clears)
Customer ID	--customer-id ID
API Endpoint	--api-endpoint URL
API Key	--api-key KEY (or DMG_API_KEY env var)
Scan Frequency	--scan-frequency HOURS
Max Execution Duration	--max-execution-duration 2h (off to disable)
Search Directories	--search-dirs DIR...
NPM / Brew / Python / runtime scan	--enable-<x>-scan / --disable-<x>-scan
Node / Python scanner	--legacy-node-scan / --disk-node-scan, --legacy-python-scan / --disk-python-scan
macOS TCC-protected dirs	--include-tcc-protected / --no-include-tcc-protected
macOS network volumes	--include-network-volumes / --no-include-network-volumes
Color Mode	--color=auto|always|never
Output Format / HTML file	--pretty, --json, --html FILE
Log Level	--log-level=LEVEL
Install Directory	--install-dir DIR
Self-update	--auto-update=BOOL, --update-mirror-url URL, --update-lag-behind N, --update-cooldown-hours N
Everything at once	--from-file config.json (flags override the file)

CLI flags always override config file values — this matches the shell script behavior. For example, if your config has output_format: json, running ./stepsecurity-dev-machine-guard --pretty uses pretty output. To clear a value during configuration, enter a single dash (-).

Logging and Verbose Mode

By default in community mode, progress messages (spinners, step details) are suppressed — you only see the final output. This keeps stdout clean for piping.

# Default: quiet — clean output, no progress spinners
./stepsecurity-dev-machine-guard --json > scan.json

# Verbose: show progress spinners and step timing
./stepsecurity-dev-machine-guard --verbose

# Fine-grained control: set log level
./stepsecurity-dev-machine-guard --log-level=info

# Save log level in config so it persists across runs
./stepsecurity-dev-machine-guard configure

In enterprise mode (send-telemetry, install), progress is always shown regardless of the log level — the output is captured as execution logs and sent to the backend for debugging.