nuc

nuc

A command-line interface for the Nucleus Security vulnerability management platform.

Installation

From source

go install github.com/marstid/nuc/cmd/nuc@latest

Build locally

git clone https://github.com/marstid/nuc.git
cd nuc
make build

The binary will be at bin/nuc.

Configuration

Set your API key

nuc config set api_key <your-api-key>

Or use an environment variable:

export NUC_API_KEY=<your-api-key>

Set your API base URL (required)

nuc config set base_url https://nucleus-eu6.nucleussec.com/nucleus/api

Or use an environment variable:

export NUC_BASE_URL=https://nucleus-eu6.nucleussec.com/nucleus/api

Note: Each Nucleus instance has a unique URL (e.g. nucleus-eu6.nucleussec.com). There is no default — you must configure this before using any API commands.

Set default project

nuc config set default_project 42

View configuration

nuc config list
nuc config path

Configuration file

The config file is stored at:

• Linux: $XDG_CONFIG_HOME/nuc/config.yaml (default ~/.config/nuc/config.yaml)
• macOS: ~/Library/Application Support/nuc/config.yaml
• Windows: %AppData%/nuc/config.yaml

Priority order

Configuration is resolved in this order (highest priority first):

1. Command-line flags (--api-key, --base-url, --project)
2. Environment variables (NUC_API_KEY, NUC_BASE_URL, NUC_PROJECT)
3. Config file

Quick Start

# List all projects
nuc projects list

# Get project details
nuc projects get 42

# Get project risk score
nuc projects riskscore 42

Usage Examples

In Nucleus, teams and services are modeled as asset groups. Use --groups (findings, metrics, trends) or --group (assets) to filter by team or service.

Discover Available Groups

# List all asset groups (teams/services) in your project
nuc assets groups list

# Just the group names (for scripting)
nuc assets groups list -q

Findings per Team/Service

# All findings for the "payment-service" group
nuc findings search --groups payment-service

# All findings for "backend-team"
nuc findings search --groups backend-team

# Multiple groups at once
nuc findings search --groups payment-service,auth-service

# Use glob patterns to match group names
nuc findings search --groups "*team-euc*"
nuc findings search --groups "*payment*,*auth*"
nuc metrics groups --groups "*backend*"

Combine Severity + Group

# Critical findings for a specific service
nuc findings search --groups payment-service --severity Critical

# High severity in the backend team
nuc findings search --groups backend-team --severity High

Findings by Status

# Active (unresolved) findings for a service
nuc findings search --groups payment-service --status Active

# Accepted-risk findings
nuc findings search --groups backend-team --status "Accepted Risk"

# Search by CVE across all groups
nuc findings search --cve CVE-2024-1234

Exploitable Findings

# Exploitable findings for a group (1=yes, 0=no)
nuc findings search --groups payment-service --exploitable 1

# Exploitable + Critical severity
nuc findings search --exploitable 1 --severity Critical

Assets per Group

# List assets in a specific team/service group
nuc assets list --group payment-service

# Filter by asset type within a group
nuc assets list --group backend-team --type Host

Note: assets list uses --group (singular); findings search, metrics groups, and findings trend use --groups (plural, comma-separated).

Metrics per Team/Service

# Compare risk across teams
nuc metrics groups --groups payment-service,auth-service,frontend

# Specific metrics for a single service
nuc metrics groups --groups payment-service --metrics risk_score,vuln_count_critical,mttr_critical_7d

# Selected security posture metrics
nuc metrics groups --groups backend-team --metrics risk_score,asset_count,vuln_count,vuln_count_critical,vuln_count_high,avg_age_critical,mttr_7d

Vulnerability Trends

# Discovery trend for a service over time
nuc findings trend --groups payment-service --start-date 2025-01-01 --end-date 2025-06-01

Mitigated Findings

# Recently mitigated findings
nuc findings mitigated --start-date 2025-05-01

# With pagination
nuc findings mitigated --start 0 --limit 50

Overview

# Project-wide severity summary
nuc findings overview

Scripting & Pipelines

# Quiet mode — just IDs for piping
nuc findings search --groups payment-service --severity Critical -q

# JSON output for jq processing
nuc findings search --groups backend-team -o json | jq '.[].finding_number'

# YAML output
nuc metrics groups --groups payment-service -o yaml

# Loop over critical findings per service
for group in payment-service auth-service frontend; do
  echo "=== $group ==="
  nuc findings search --groups "$group" --severity Critical -q
done

Output Formats

By default, nuc outputs human-readable tables when connected to a terminal and JSON when piped.

# Force JSON output
nuc projects list -o json

# Force table output
nuc projects list -o table

# Quiet mode — only print IDs (useful for scripting)
nuc projects list -q

Global Flags

Development

Prerequisites

• Go 1.22+
• golangci-lint

Commands

make build    # Build the binary
make test     # Run tests with race detection
make lint     # Run linter
make fmt      # Format code
make vet      # Run go vet
make install  # Install to $GOPATH/bin
make clean    # Remove build artifacts

Disclaimer

This project is an independent, community-maintained open source CLI. It is not affiliated with, endorsed by, or connected to Nucleus Security in any way. Nucleus Security is a trademark of its respective owners.

License

MIT — see LICENSE.