feat(cli): nullify deps analyze — CI-aware dependency malware-analysis workflow (#142)

* feat(cli): nullify deps analyze — CI-aware dependency malware-analysis workflow

Hand-written workflow command (not generated from OpenAPI) that wires
the Phase 5a/5b malware analyzer into customer CI pipelines via scpm's
/scpm/dependencies/analyze endpoint.

Components:

- internal/ci/ — extensible CI provider registry. Nine concrete
  Providers: GitHubActions, GitLabCI, CircleCI, BitbucketPipelines,
  Jenkins, AzureDevOps, GoogleCloudBuild, AWSCodeBuild, Local (last;
  always matches). Each exposes Platform() (matches the
  benchmarks.PipelinePlatform enum), Detect() (env-var signature),
  BaseRef / HeadRef (context-aware; fall back to
  `git rev-parse origin/HEAD` when CI doesn't expose a base),
  PRNumber, RepoSlug, and EnrichHeader (stamps CI metadata on outbound
  HTTP so scpm's audit log can tie back to the CI run).

- internal/scan/manifest/ — per-ecosystem lockfile parsers:
  npm (package-lock.json v2/v3), pypi (requirements.txt), go (go.sum),
  rust (Cargo.lock), ruby (Gemfile.lock). Each implements Parser and is
  registered in manifest.DefaultParsers(). Deliberately tight:
  pnpm-lock, poetry.lock, pom.xml, composer.lock, packages.lock.json
  are follow-up work. Every parser produces the same flat Entry
  (Ecosystem, Name, Version, File, Direct) shape so diff.go can
  compare them uniformly.

- internal/scan/diff.go — the (base, head) diff. Uses
  `git diff --name-only base..head` to list changed files, filters to
  those a parser matches, then `git show <ref>:<path>` on each side +
  parse + set-difference. Produces ChangedDep{added, bumped, removed}.

- internal/commands/deps_analyze.go — the cobra command. Flow:
    1. Detect CI provider; resolve base (--base or provider.BaseRef)
       and head (--head or provider.HeadRef) to commit SHAs.
    2. scan.Diff → list of changed deps.
    3. For each added/bumped dep, POST to
       {client.BaseURL}/scpm/dependencies/analyze with the CI-provider
       headers + an idempotency key derived from CI run ID + package
       tuple (so re-runs of the same CI build hit cached jobs).
    4. Render results as text (default) or json.
    5. Exit per --fail-on (none|vulnerable|suspicious|malicious):
       0=clean, 10=vulnerable, 20=suspicious, 30=malicious, 2=invalid
       invocation, 1=transient.

The scpm calls are hand-rolled HTTP POSTs rather than generated
api.Client methods because scpm's OpenAPI regen happens in a separate
pipeline — the CLI's scripts/generate/main.go will supersede these
once the spec lands. Follows the RegisterContextPushCommand pattern.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* style(cli): gofmt doc-comment blocks in CI provider files

golangci-lint v2.12.0 gofmt flagged the space-indented env-var tables in
the AWS CodeBuild / Azure DevOps / Bitbucket provider doc comments; reflow
to the Go 1.19 preformatted form (blank // + tab indent).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* style(cli): gofmt remaining deps-analyze files

Reflow the rest of the CI-provider doc-comment tables to Go 1.19
preformatted form, and fix const/var/struct-tag alignment in
deps_analyze.go and npm_lock.go. golangci-lint caps gofmt reports at 3 per
run, so these surfaced only after the first batch was fixed.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(cli): make deps-analyze gate functional + add tests

Addresses review of the deps-analyze workflow.

Blockers:
- Wire ExitCodeFromError in main.go so the severity exit codes
  (10/20/30) actually fire — previously every result exited 1, so the
  CI merge-gate was inert. Set SilenceUsage so a verdict failure doesn't
  print cobra usage.
- Fix --fail-on=none, which always exited 10: checkFailOn now treats a
  zero-rank threshold as "never fail".

Correctness:
- renderResults no longer index-zips two parallel slices (a mid-list
  analyze failure misattributed verdicts to the wrong package and
  dropped the tail). One analyzedDep{dep,resp,err} entry per dep now.
- Unknown/unrecognised non-empty verdicts fail closed: warn and treat as
  malicious so a server-side rename can't silently bypass the gate.
- Provider BaseRef/HeadRef + resolveRef take repoPath and set cmd.Dir,
  so --repo is honoured (ref resolution no longer runs in the CWD).

Feature:
- Implement --wait (was parsed but unused): poll by re-POSTing the
  idempotent analyze request until the job is terminal or --wait-timeout
  elapses; adds --wait-timeout/--wait-interval. An incomplete analysis
  now exits transiently (1) instead of greenlighting the merge.

Cleanup:
- Typed enums replace magic strings: ci.Platform, scan.ChangeKind,
  manifest.Ecosystem, commands.Verdict.
- Remove the `var _ = fmt.Sprintf` hack and the //nolint:errcheck.
- Correct the doc comments that claimed a benchmarks.PipelinePlatform
  enum and a `make lint-ci-providers` target that don't exist.
- Fix the misleading idempotency-key comment; handle SSH repo URLs in
  AWSCodeBuild.RepoSlug; note fetch-depth:0 for GitHub push diffs.

Tests:
- Add unit tests for the five lockfile parsers, diffEntries, CI provider
  detection/parsing, and the verdict/gate/render/wait/exit-code logic.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: tim-thacker-nullify

cmd/cli/cmd/root.go

@@ -104,6 +104,11 @@ func init() {
 	commands.RegisterOrchestratorCommands(apiCmd, getAPIClient)
 	commands.RegisterAssetGraphCommands(apiCmd, getAPIClient)
 	commands.RegisterInfrastructureCommands(apiCmd, getAPIClient)
+
+	// Hand-written workflow — not generated from OpenAPI. Routes through
+	// scpm's /scpm/dependencies/analyze. Wired at top level (not under
+	// apiCmd) so `nullify deps analyze` reads naturally in CI scripts.
+	commands.RegisterDepsAnalyzeCommand(rootCmd, getAPIClient)
 }
 
 func setupLogger(ctx context.Context) context.Context {

cmd/cli/main.go

@@ -4,10 +4,14 @@ import (
 	"os"
 
 	"github.com/nullify-platform/cli/cmd/cli/cmd"
+	"github.com/nullify-platform/cli/internal/commands"
 )
 
 func main() {
+	// commands.ExitCodeFromError maps the deps-analyze workflow's
+	// exit-coded errors (severity gate: 10/20/30, invalid: 2, transient:
+	// 1) onto the process exit code; any other error falls back to 1.
 	if err := cmd.Execute(); err != nil {
-		os.Exit(1)
+		os.Exit(commands.ExitCodeFromError(err))
 	}
 }

internal/ci/aws_codebuild.go

@@ -0,0 +1,85 @@
+package ci
+
+import (
+	"context"
+	"net/http"
+	"os"
+	"strings"
+)
+
+// AWSCodeBuild — https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-env-vars.html
+//
+// Key envs:
+//
+//	CODEBUILD_BUILD_ID              signature
+//	CODEBUILD_RESOLVED_SOURCE_VERSION  head
+//	CODEBUILD_WEBHOOK_BASE_REF      base (webhook-triggered PRs)
+//	CODEBUILD_SOURCE_REPO_URL       https://github.com/org/repo.git
+type AWSCodeBuild struct{}
+
+func NewAWSCodeBuild() Provider { return &AWSCodeBuild{} }
+
+func (a *AWSCodeBuild) Platform() Platform { return PlatformAWSCodeBuild }
+
+func (a *AWSCodeBuild) Detect() bool { return os.Getenv("CODEBUILD_BUILD_ID") != "" }
+
+func (a *AWSCodeBuild) BaseRef(ctx context.Context, repoPath string) (string, error) {
+	// CODEBUILD_WEBHOOK_BASE_REF is "refs/heads/main" shape — strip the
+	// prefix + resolve.
+	if v := os.Getenv("CODEBUILD_WEBHOOK_BASE_REF"); v != "" {
+		return resolveRef(ctx, repoPath, "origin/"+strings.TrimPrefix(v, "refs/heads/"))
+	}
+	return resolveRef(ctx, repoPath, "origin/HEAD")
+}
+
+func (a *AWSCodeBuild) HeadRef(ctx context.Context, repoPath string) (string, error) {
+	if v := os.Getenv("CODEBUILD_RESOLVED_SOURCE_VERSION"); v != "" {
+		return v, nil
+	}
+	return resolveRef(ctx, repoPath, "HEAD")
+}
+
+func (a *AWSCodeBuild) PRNumber() (int, bool) {
+	// CODEBUILD_WEBHOOK_TRIGGER sometimes has "pr/123" shape.
+	trigger := os.Getenv("CODEBUILD_WEBHOOK_TRIGGER")
+	if !strings.HasPrefix(trigger, "pr/") {
+		return 0, false
+	}
+	n := 0
+	for _, c := range trigger[3:] {
+		if c < '0' || c > '9' {
+			return 0, false
+		}
+		n = n*10 + int(c-'0')
+	}
+	return n, true
+}
+
+func (a *AWSCodeBuild) RepoSlug() (string, string, bool) {
+	repoURL := os.Getenv("CODEBUILD_SOURCE_REPO_URL")
+	if repoURL == "" {
+		return "", "", false
+	}
+	// Strip trailing .git. Handle both HTTPS
+	// ("https://github.com/owner/repo.git") and SSH
+	// ("git@github.com:owner/repo.git") forms: in the SSH shape the
+	// owner is separated from the host by ':', so normalise that to '/'
+	// before taking the final "owner/name" segments.
+	trimmed := strings.TrimSuffix(repoURL, ".git")
+	trimmed = strings.ReplaceAll(trimmed, ":", "/")
+	parts := strings.Split(trimmed, "/")
+	if len(parts) < 2 {
+		return "", "", false
+	}
+	return parts[len(parts)-2], parts[len(parts)-1], true
+}
+
+func (a *AWSCodeBuild) EnrichHeader(h http.Header) {
+	if v := os.Getenv("CODEBUILD_BUILD_ID"); v != "" {
+		h.Set("X-Nullify-CI-Run-ID", v)
+	}
+	if v := os.Getenv("CODEBUILD_RESOLVED_SOURCE_VERSION"); v != "" {
+		h.Set("X-Nullify-CI-Commit", v)
+	}
+	h.Set("X-Nullify-CI-Provider", a.Platform().String())
+}

internal/ci/azure_devops.go

@@ -0,0 +1,73 @@
+package ci
+
+import (
+	"context"
+	"net/http"
+	"os"
+	"strconv"
+)
+
+// AzureDevOps — https://learn.microsoft.com/en-us/azure/devops/pipelines/build/variables
+//
+// Key envs:
+//
+//	TF_BUILD=True                            signature
+//	BUILD_SOURCEVERSION                      head commit
+//	SYSTEM_PULLREQUEST_TARGETBRANCHNAME      target branch (PR builds)
+//	SYSTEM_PULLREQUEST_PULLREQUESTNUMBER     PR number
+//	BUILD_REPOSITORY_NAME                    repo name (no owner)
+//	BUILD_BUILDID                            run id
+type AzureDevOps struct{}
+
+func NewAzureDevOps() Provider { return &AzureDevOps{} }
+
+func (a *AzureDevOps) Platform() Platform { return PlatformAzureDevOps }
+
+func (a *AzureDevOps) Detect() bool { return os.Getenv("TF_BUILD") == "True" }
+
+func (a *AzureDevOps) BaseRef(ctx context.Context, repoPath string) (string, error) {
+	if v := os.Getenv("SYSTEM_PULLREQUEST_TARGETBRANCHNAME"); v != "" {
+		return resolveRef(ctx, repoPath, "origin/"+v)
+	}
+	return resolveRef(ctx, repoPath, "HEAD^")
+}
+
+func (a *AzureDevOps) HeadRef(ctx context.Context, repoPath string) (string, error) {
+	if v := os.Getenv("BUILD_SOURCEVERSION"); v != "" {
+		return v, nil
+	}
+	return resolveRef(ctx, repoPath, "HEAD")
+}
+
+func (a *AzureDevOps) PRNumber() (int, bool) {
+	v := os.Getenv("SYSTEM_PULLREQUEST_PULLREQUESTNUMBER")
+	if v == "" {
+		return 0, false
+	}
+	n, err := strconv.Atoi(v)
+	if err != nil {
+		return 0, false
+	}
+	return n, true
+}
+
+func (a *AzureDevOps) RepoSlug() (string, string, bool) {
+	// Azure uses Organization/Project/Repo — not a two-part slug.
+	// Collapse Organization as the "owner" field.
+	owner := os.Getenv("SYSTEM_COLLECTIONURI")
+	name := os.Getenv("BUILD_REPOSITORY_NAME")
+	if name == "" {
+		return "", "", false
+	}
+	return owner, name, true
+}
+
+func (a *AzureDevOps) EnrichHeader(h http.Header) {
+	if v := os.Getenv("BUILD_BUILDID"); v != "" {
+		h.Set("X-Nullify-CI-Run-ID", v)
+	}
+	if v := os.Getenv("BUILD_SOURCEVERSION"); v != "" {
+		h.Set("X-Nullify-CI-Commit", v)
+	}
+	h.Set("X-Nullify-CI-Provider", a.Platform().String())
+}

internal/ci/bitbucket_pipelines.go

@@ -0,0 +1,72 @@
+package ci
+
+import (
+	"context"
+	"net/http"
+	"os"
+	"strconv"
+)
+
+// BitbucketPipelines — https://support.atlassian.com/bitbucket-cloud/docs/variables-and-secrets/
+//
+// Key envs:
+//
+//	BITBUCKET_BUILD_NUMBER          signature
+//	BITBUCKET_COMMIT                head
+//	BITBUCKET_PR_DESTINATION_BRANCH target branch (PR builds)
+//	BITBUCKET_PR_ID                 PR number
+//	BITBUCKET_REPO_OWNER / REPO_SLUG
+type BitbucketPipelines struct{}
+
+func NewBitbucketPipelines() Provider { return &BitbucketPipelines{} }
+
+func (b *BitbucketPipelines) Platform() Platform { return PlatformBitbucketPipelines }
+
+func (b *BitbucketPipelines) Detect() bool {
+	return os.Getenv("BITBUCKET_BUILD_NUMBER") != ""
+}
+
+func (b *BitbucketPipelines) BaseRef(ctx context.Context, repoPath string) (string, error) {
+	if v := os.Getenv("BITBUCKET_PR_DESTINATION_BRANCH"); v != "" {
+		return resolveRef(ctx, repoPath, "origin/"+v)
+	}
+	return resolveRef(ctx, repoPath, "HEAD^")
+}
+
+func (b *BitbucketPipelines) HeadRef(ctx context.Context, repoPath string) (string, error) {
+	if v := os.Getenv("BITBUCKET_COMMIT"); v != "" {
+		return v, nil
+	}
+	return resolveRef(ctx, repoPath, "HEAD")
+}
+
+func (b *BitbucketPipelines) PRNumber() (int, bool) {
+	v := os.Getenv("BITBUCKET_PR_ID")
+	if v == "" {
+		return 0, false
+	}
+	n, err := strconv.Atoi(v)
+	if err != nil {
+		return 0, false
+	}
+	return n, true
+}
+
+func (b *BitbucketPipelines) RepoSlug() (string, string, bool) {
+	owner := os.Getenv("BITBUCKET_REPO_OWNER")
+	name := os.Getenv("BITBUCKET_REPO_SLUG")
+	if owner == "" || name == "" {
+		return "", "", false
+	}
+	return owner, name, true
+}
+
+func (b *BitbucketPipelines) EnrichHeader(h http.Header) {
+	if v := os.Getenv("BITBUCKET_BUILD_NUMBER"); v != "" {
+		h.Set("X-Nullify-CI-Run-ID", v)
+	}
+	if v := os.Getenv("BITBUCKET_COMMIT"); v != "" {
+		h.Set("X-Nullify-CI-Commit", v)
+	}
+	h.Set("X-Nullify-CI-Provider", b.Platform().String())
+}

internal/ci/ci.go

@@ -0,0 +1,86 @@
+// Package ci detects the CI/CD platform the CLI is currently running under
+// and exposes the base/head commit refs it needs to compute changed
+// dependencies.
+//
+// Implementations are registered in priority order in registry.go.
+// Detect() returns the first provider whose env-var signature matches;
+// the Local fallback is last so an unrecognised CI still works off
+// `git rev-parse` defaults.
+//
+// Each provider reports a Platform value from the locally-defined set of
+// constants below. When adding a provider, define its constant here and
+// return it from Platform().
+package ci
+
+import (
+	"context"
+	"errors"
+	"net/http"
+)
+
+// Platform is the canonical identifier for a CI/CD platform. Values are
+// stamped onto the X-Nullify-CI-Provider header so scpm's audit log can
+// attribute a CLI run to its CI environment.
+type Platform string
+
+const (
+	PlatformGitHubActions      Platform = "GITHUB_ACTIONS"
+	PlatformGitLabCI           Platform = "GITLAB_CI"
+	PlatformCircleCI           Platform = "CIRCLECI"
+	PlatformBitbucketPipelines Platform = "BITBUCKET_PIPELINES"
+	PlatformJenkins            Platform = "JENKINS"
+	PlatformAzureDevOps        Platform = "AZURE_DEVOPS"
+	PlatformGoogleCloudBuild   Platform = "GOOGLE_CLOUD_BUILD"
+	PlatformAWSCodeBuild       Platform = "AWS_CODEBUILD"
+	PlatformOther              Platform = "OTHER"
+)
+
+func (p Platform) String() string { return string(p) }
+
+// Provider identifies one CI/CD platform and exposes the information
+// the CLI's deps-analyze + containers-analyze workflows need. All
+// methods are expected to be cheap — provider detection happens on
+// every CLI invocation.
+type Provider interface {
+	// Platform returns this provider's Platform constant.
+	Platform() Platform
+
+	// Detect returns true when the current process env matches this
+	// provider's signature. Detect MUST NOT touch the network or
+	// filesystem — env var inspection only.
+	Detect() bool
+
+	// BaseRef returns the commit or ref (short sha, full sha, or
+	// branch name) the CI declared as the base of the current build,
+	// resolved against the git repository at repoPath. For PR builds,
+	// this is the PR target branch's HEAD at PR open time; for push
+	// builds, it's the previous HEAD of the pushed branch. Fall back to
+	// "origin/<default-branch>" when CI doesn't expose a specific base.
+	BaseRef(ctx context.Context, repoPath string) (string, error)
+
+	// HeadRef returns the commit the current build is running against,
+	// resolved against the git repository at repoPath. For PR builds,
+	// this is the PR's head commit; for push builds, the pushed commit.
+	HeadRef(ctx context.Context, repoPath string) (string, error)
+
+	// PRNumber returns the pull-request number if the current build is
+	// a PR, and (0, false) otherwise. Used for diagnostic logging + as
+	// the idempotency-key prefix in scpm calls.
+	PRNumber() (int, bool)
+
+	// RepoSlug returns (owner, name) for GitHub/GitLab/Bitbucket-style
+	// coordinates. Returns (_, _, false) when the provider doesn't
+	// expose it (eg. Jenkins, self-hosted CI).
+	RepoSlug() (owner, name string, ok bool)
+
+	// EnrichHeader adds CI-specific headers to outbound HTTP requests
+	// (commit SHA, PR number, run ID) so scpm's audit log can tie a
+	// specific CLI run back to a CI invocation. Called once per HTTP
+	// request built by the workflow.
+	EnrichHeader(h http.Header)
+}
+
+// ErrNoProvider is returned by Detect when no registered provider
+// matches — shouldn't happen in practice because the Local fallback
+// always returns true, but declared so callers can assert on it.
+var ErrNoProvider = errors.New("no CI provider detected")