<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->
---
name: detecting-dependency-confusion
description: >-
  Detect and prevent dependency confusion attacks where internal package names
  are claimed on public registries. Audit namespace conflicts across npm, PyPI,
  and Maven registries with automated monitoring and CI/CD guardrails.
domain: cybersecurity
subdomain: supply-chain-security
tags:
  - dependency-confusion
  - npm-security
  - pypi-security
  - namespace-hijacking
  - supply-chain-attack
  - package-security
version: "1.0"
author: defconxt
license: AGPL-3.0
metadata:
  mitre-attack: ["T1195.002"]
---

# Detecting Dependency Confusion

## Overview

Dependency confusion exploits the way package managers resolve names when both
internal and public registries are configured. An attacker publishes a higher-version
package on the public registry with the same name as an internal package — the
package manager installs the public (malicious) version. This skill covers
detection, monitoring, and prevention across npm, PyPI, and Maven ecosystems.

Mode: `[MODE: BLUE]` — Detect namespace conflicts; `[MODE: RED]` — Simulate dependency confusion attacks.

## Prerequisites

| Requirement | Details |
|---|---|
| Python 3.10+ with `requests` and `packaging` | Required |
| npm CLI for registry queries | Required |
| pip for PyPI registry queries | Required |
| Access to internal package registry (Artifactory, Nexus, GitLab Packages) | Required |
| jq for JSON processing | Required |

## Key Concepts

### Public Registry Probing

```bash
# Check if internal package name exists on npm
npm view @internal/company-utils 2>/dev/null && echo "EXISTS on npm" || echo "SAFE"

# Check if internal package name exists on PyPI
pip index versions company-internal-lib 2>/dev/null && echo "EXISTS on PyPI" || echo "SAFE"

# Batch check — npm
for pkg in $(cat internal-packages.txt); do
  if npm view "$pkg" version 2>/dev/null; then
    echo "CONFLICT: $pkg exists on public npm"
  fi
done

# Check Maven Central
curl -s "https://search.maven.org/solrsearch/select?q=a:internal-artifact&rows=1" | \
  jq '.response.numFound'
```

### Prevention Strategies

```bash
# npm — use scoped packages (@company/package-name)
npm init --scope=@company

# npm — configure registry per scope
npm config set @company:registry https://npm.internal.company.com/

# pip — configure primary index as internal
pip install --index-url https://pypi.internal.company.com/simple/ \
  --extra-index-url https://pypi.org/simple/ package-name

# pip — pin to internal registry only for internal packages
# In pip.conf:
# [global]
# index-url = https://pypi.internal.company.com/simple/
# extra-index-url = https://pypi.org/simple/

# Artifactory — enable priority resolution
# Set internal repo with higher priority than remote PyPI proxy
```

### CI/CD Guardrails

```yaml
# GitHub Actions — dependency confusion check
- name: Check for dependency confusion
  run: |
    node scripts/agent.js --action scan \
      --manifest package.json \
      --registry npm \
      --output /tmp/confusion-report.json
    if jq -e '.conflicts | length > 0' /tmp/confusion-report.json; then
      echo "::error::Dependency confusion risk detected"
      exit 1
    fi
```

## Workflow

### Step 1: Scan for Namespace Conflicts

```bash
node scripts/agent.js --action scan --manifest package.json --registry npm --output /tmp/confusion.json
```

### Step 2: Monitor Public Registries

```bash
node scripts/agent.js --action monitor --packages internal-packages.txt --registry pypi --output /tmp/monitor.json
```

### Step 3: Validate Registry Configuration

```bash
node scripts/agent.js --action validate --config .npmrc --output /tmp/config-check.json
```

## Detection

```yaml
title: Dependency Confusion Detection
id: 8ee9ea81-b0ee-43f6-9299-c431f37ba5d9
status: experimental
description: Detects suspicious activity related to detecting dependency confusion techniques in supply chain security context
logsource:
  category: process_creation
  product: linux
detection:
  selection:
    CommandLine: "*detecting*dependency*"
  condition: selection
level: medium
tags:
  - attack.t1195.002
  - attack.initial_access
falsepositives:
  - Package manager performing routine dependency resolution
```


**Detection Opportunities**

| Indicator | Source | Detection Logic |
|---|---|---|
| Dependency Confusion Detection | linux/process_creation | Sigma rule (medium) |
| ATT&CK Coverage | MITRE ATT&CK | T1195.002 |

## Verification

- [ ] All internal packages use scoped namespaces (@company/ prefix for npm)
- [ ] Public registry probed for every internal package name
- [ ] CI pipeline includes dependency confusion check gate
- [ ] Registry priority configured correctly (internal > public)
- [ ] Lock files pinned to specific registry URLs
- [ ] Monitoring alerts configured for new public package name collisions

## References

- [Dependency Confusion — Alex Birsan](https://medium.com/@alex.birsan/dependency-confusion-4a5d60fec610)
- [npm Scoped Packages](https://docs.npmjs.com/cli/v10/using-npm/scope)
- [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/)
- [MITRE ATT&CK T1195.001](https://attack.mitre.org/techniques/T1195/001/)
