### Nix```bash
nix profile install github:brennhill/sloppy-joe

### 2. 타이포스쿼팅 (생성적 검사 + 편집 거리 대체)

**공격:** 공격자가 `expresz`를 npm에 등록합니다. 이것은 `express`에서 한 글자가 변경된 것입니다. AI가 생성하거나 개발자가 오타를 냅니다. 이 패키지는 존재하며, 존재 여부 검사를 통과하고 맬웨어를 설치합니다.

**sloppy-joe가 이를 차단하는 방법:** sloppy-joe는 편집 거리로 대체되기 전에 10개의 생성적 검사를 실행합니다. 각 생성적 검사는 종속성 이름의 특정 변형을 생성합니다 (문자 교환, 반복 축소, 접미사 제거, 단어 재정렬, 구분자 정규화, 호모글리프 대체, 스코프 확인) 그리고 알려진 인기 패키지와 정확히 일치하는지 테스트합니다. 이 접근 방식은 [Rust Foundation의 Typomania](https://github.com/rustfoundation/typomania) 라이브러리에서 영감을 받았으며, 변형 후 정확히 일치하는 경우에만 작동하므로 오탐이 거의 없습니다.

Levenshtein 편집 거리는 특정 검사에서 예상하지 못한 새로운 변형에 대한 안전망으로 마지막에 실행됩니다. 이들은 함께 알려진 공격 패턴(정확히)과 알려지지 않은 패턴(광범위하게)을 모두 커버합니다.```
ERROR expresz [similarity/edit-distance]
      'expresz' is 1 character away from 'express'. This could be a typosquat.
 Fix: If you meant 'express', fix the name in your manifest.

### 4. 구분자 혼동

**공격:** `python-dateutil` 대 `python_dateutil` 대 `pythondateutil`. 일부 레지스트리에서는 이들이 서로 다른 패키지입니다. 공격자가 변형을 등록합니다.

**sloppy-joe가 차단하는 방법:** 비교 전에 모든 구분자(`-`, `_`, `.`)를 정규화합니다. 정규화된 형태가 알려진 패키지와 일치하면 플래그가 지정됩니다.```
ERROR socket_io [similarity/separator-confusion]
      'socket_io' matches 'socket.io' after normalizing separators.
 Fix: Use the canonical name 'socket.io' with the correct separators.

### 6. 인접 문자 교환

**공격:** `reqeust` 대신 `request`. 두 인접 문자가 전치된 일반적인 오타로, 공격자가 악용합니다.

**sloppy-joe가 이를 차단하는 방법:** 의존성 이름의 모든 인접 교환 변형을 생성하여 각각을 코퍼스와 대조합니다.```
ERROR reqeusts [similarity/char-swap]
      'reqeusts' matches 'requests' with two adjacent characters swapped.
 Fix: Use 'requests' — two characters are transposed.

### 8. 호모글리프(시각적 유사 문자)

**공격:** 키릴 문자 `е`(U+0435)가 라틴 문자 `e`(U+0065) 대신 사용된 `rеquests`. 시각적으로 동일합니다. 패키지 이름이 `requests`와 똑같이 보이지만 다른 악성 패키지로 연결됩니다.

**sloppy-joe가 차단하는 방법:** 17개의 알려진 호모글리프 문자(키릴 문자, 전각 문자, 필기체 변형)를 해당 라틴 문자로 대체한 후 결과가 알려진 패키지와 일치하는지 확인합니다.```
ERROR rеquests [similarity/homoglyph]
      'rеquests' contains characters that look identical to 'requests'
      but are different Unicode codepoints (homoglyphs).
 Fix: Replace the lookalike characters with standard ASCII.

### 10. 대소문자 변형 공격 (대소문자 구분 레지스트리)

**공격:** Go, Maven, Ruby에서는 `Rails`와 `rails`가 서로 다른 패키지입니다. 공격자는 대문자 변형을 등록합니다.

**sloppy-joe가 차단하는 방법:** 대소문자를 구분하는 레지스트리에서는 알려진 패키지의 대소문자 변형이 오류로 플래그 지정됩니다. 대소문자를 구분하지 않는 레지스트리(npm, PyPI, Cargo, NuGet, PHP)에서는 대소문자 변형이 안전하므로 건너뜁니다.```
ERROR Rails [similarity/case-variant]
      'Rails' differs from 'rails' only in letter casing.
      On case-sensitive registries (ruby) these resolve to different packages.
 Fix: Use the exact casing 'rails' in your manifest.

### 12. 스코프 스쿼팅 (npm, PHP, Go, JVM)

**공격:** 공격자는 `@typos/lodash`를 npm에 등록합니다 — `@types/lodash`와 한 글자 차이입니다. 또는 Packagist에 `larvael/framework` — `laravel/framework`와 두 글자 차이입니다. 또는 Go에 `github.com/gooogle/protobuf` — `o`가 하나 더 많습니다. 스코프가 언뜻 보기에는 합법적으로 보입니다. 패키지가 확인됩니다. 악성코드가 설치됩니다.

이는 드물지만 가능성이 있는 일이며 — "드물지만 가능성 있는" 것이 바로 sloppy-joe가 존재하는 이유입니다. 2021년 `ua-parser-js` 사건은 스코프 관련이었습니다. 주간 다운로드 수가 수백만인 패키지에서 발생할 수 있다면, 여러분의 패키지에서도 발생할 수 있습니다.

**sloppy-joe가 차단하는 방법:** 의존성 이름에서 스코프/네임스페이스를 추출하고 편집 거리를 사용하여 알려진 양호한 스코프 목록과 비교합니다. npm(`@scope`), PHP(`vendor/`), Go(`github.com/org`), JVM(`com.group`)에서 작동합니다.```
ERROR @typos/lodash [similarity/scope-squatting]
      Scope '@typos' is 1 character away from the known scope '@types'.
      Scope squatting is a known supply chain attack vector.
 Fix: If you meant '@types/lodash', fix the scope in your manifest.

### 13. 비정규 패키지 (공격이 아님 — 일관성 게이트)

**공격:** 공격이 아님 — 일관성 문제입니다. AI가 학습 데이터에서 인기가 많았던 `moment`를 선택했지만, 팀은 `dayjs`를 사용합니다. 동일한 작업에 대해 서로 다른 팀이 다른 패키지를 사용하면 유지보수 부채와 의존성 팽창이 발생합니다.

**sloppy-joe가 차단하는 방법:** 구성 파일에서 각 표준 패키지를 거부된 대안에 매핑합니다. 종속성이 대안과 일치하면 빌드가 실패합니다.```
ERROR moment [canonical]
      'moment' is not the approved package for this purpose.
      Your team uses 'dayjs'.
 Fix: Replace 'moment' with 'dayjs' in your manifest file.

### 15. 새로 생성된 패키지

**공격:** 어제 생성되었고 다운로드 수가 3회인 패키지로, 인기 패키지와 유사한 이름을 가지고 있습니다. 오타 스쿼트나 향후 공격을 위한 자리채움(placeholder)일 가능성이 높습니다.

**sloppy-joe의 차단 방법:** 30일 미만 전에 생성된 모든 패키지를 플래그합니다.```
ERROR sketchy-lib [metadata/new-package]
      'sketchy-lib' was first published 2 days ago.
      New packages are higher risk.
 Fix: Verify 'sketchy-lib' at its registry page and source repository.

---

## 지원되는 생태계

| 생태계 | 매니페스트 | Lockfile 정책 | 존재 여부 | 메타데이터 | 연령 게이트 |
|-----------|----------|-----------------|:---------:|:--------:|:--------:|
| npm | package.json | `package-lock.json` 또는 `npm-shrinkwrap.json` 필수 | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| PyPI | `pyproject.toml`, `requirements*.txt`, `Pipfile`, `setup.cfg`, `setup.py` | Poetry는 `poetry.lock`으로 신뢰되고, uv는 `uv.lock`으로 신뢰되며, 완전히 해시 잠긴 pip-tools는 커밋된 requirements 그래프가 `--index-url`과 정확히 허용된 `--extra-index-url` 값을 바인딩할 때만 신뢰되며, 리포지토리에서 볼 수 있는 Poetry/uv 사용자 정의 인덱스는 정확한 `trusted_indexes.pypi` 허용 목록에 의해서만 신뢰될 수 있습니다. 레거시 매니페스트는 `python_enforcement`가 `poetry_only`인 경우를 제외하고 매 실행마다 경고합니다. | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| Cargo | Cargo.toml | `Cargo.lock` 필수 | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| Go | go.mod | `go.sum`은 외부 종속성에 필수; stdlib 전용 또는 전체 로컬 `replace`에는 필요하지 않음 | :white_check_mark: | :x: | :x: |
| Ruby | Gemfile | `Gemfile.lock` 필수 | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| PHP | composer.json | `composer.lock` 필수 | :white_check_mark: | :x: | :x: |
| JVM (Gradle) | build.gradle / build.gradle.kts | `gradle.lockfile` 필수 | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| JVM (Maven) | pom.xml | 경고 전용: 엄격한 lockfile 적용 없음 | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| .NET | *.csproj | `packages.lock.json` 필수 | :white_check_mark: | :x: | :x: |

모든 생태계는 존재 여부, 유사성, 표준 검사를 받습니다. 메타데이터와 연령 게이트는 레지스트리 API가 노출하는 항목에 따라 달라집니다. Lockfile 지원을 통해 생태계가 신뢰할 수 있는 프로젝트 로컬 lockfile 모델을 제공하는 경우 전이적 종속성 스캐닝과 정확한 버전 해결이 가능합니다.

## 빠른 시작```bash
# Install
cargo install sloppy-joe

# Check current project (auto-detects ecosystem)
sloppy-joe check

# Check with canonical enforcement and age gate
sloppy-joe check --config /etc/sloppy-joe/config.json

# Output as JSON for CI
sloppy-joe check --json

**`canonical`** — 키는 승인된 패키지, 값은 거부된 대안입니다.

**`internal`** — 조직의 패키지입니다. 모든 검사를 건너뜁니다. 이들은 지속적으로 변경됩니다.

**`allowed`** — 검증된 외부 패키지입니다. 존재 여부 및 유사성 검사를 건너뛰지만, 여전히 버전 기간 게이트의 적용을 받습니다.

**`similarity_exceptions`** — 검토된 유사성 오탐지에 대한 정확한 패키지/후보/생성기 억제입니다. 특정 유사성 에지가 잘못되었지만 패키지에 대한 정상 검사를 원할 때 사용합니다.

**`metadata_exceptions`** — 검토된 메타데이터 억제입니다. 현재는 `metadata/maintainer-change`만 지원하며, 정확한 패키지/버전/이전 게시자/현재 게시자 일치가 필요합니다.

유지자 변경 차단을 검토해야 할 때 `sloppy-joe check --review-exceptions`를 사용하세요. 스캔은 여전히 정상적으로 차단되지만, 사람이 읽을 수 있는 출력에는 소유자, 저장소 URL, 복사하여 붙여넣을 수 있는 `metadata_exceptions` 스니펫이 포함된 `REVIEW EXCEPTIONS` 섹션이 추가됩니다. `--json`은 동일한 데이터를 최상위 `review_candidates` 필드에 포함합니다.

**`min_version_age_hours`** — 이 시간보다 전에 게시된 버전을 차단합니다. 기본값: 72(3일). 비활성화하려면 0으로 설정하세요. 내부 패키지는 면제됩니다.

**`allow_legacy_npm_v1_lockfile`** — 축소된 신뢰 모드에서 npm v5/v6의 `lockfileVersion: 1` npm 잠금 파일을 허용합니다. 기본값: `false`. 레거시 npm에 의도적으로 고정되어 있고 큰 경고와 축소된 신뢰할 수 있는 npm 전이 적용 범위를 수용하지 않는 한 이 옵션을 끄십시오.

**`python_enforcement`** — Python 신뢰 정책을 제어합니다. `prefer_poetry`(기본값)는 Poetry 프로젝트와 uv 프로젝트를 신뢰하며, 커밋된 요구사항 그래프가 `--index-url` 및 모든 비PyPI `--extra-index-url` 값을 정확히 바인딩하는 경우에만 완전 해시 잠금된 pip-tools 요구사항을 신뢰하고, 그렇지 않으면 pip-tools를 축소된 신뢰로 강등합니다. 해시되지 않은 `requirements*.txt`, `Pipfile`, `setup.cfg`, `setup.py`, Poetry/uv가 아닌 `pyproject.toml`과 같은 레거시 매니페스트는 실행할 때마다 경고합니다. `poetry_only`는 이러한 비Poetry Python 워크플로를 차단하고 Poetry를 요구합니다.

### 구성 보안

구성은 **프로젝트 디렉토리에서 절대 읽지 않습니다**. 셸 접근 권한이 있는 AI 에이전트가 저장소 내 구성을 다시 작성하여 원하는 모든 것을 허용 목록에 추가할 수 있습니다.

구성 해결:
1. `--config /path/to/config.json` — 로컬 파일(CLI 플래그, 최고 우선순위)
2. `--config https://example.com/config.json` — URL에서 가져오기
3. `SLOPPY_JOE_CONFIG=...` — 환경 변수(파일 경로 또는 URL)
4. 구성 없음 = 존재 여부 + 유사성 + 메타데이터 검사만 수행

잘못된 구성은 실행 가능한 오류 메시지와 함께 **하드 실패**합니다 — 손상된 구성이 조용히 보호 없음으로 대체되지 않습니다.

전체 형식 참조, CI 통합 패턴 및 예제는 [CONFIG.md](https://github.com/brennhill/sloppy-joe/blob/main/CONFIG.md)를 참조하세요.

부트스트랩 구성:```bash
sloppy-joe init --greenfield --ecosystem npm
sloppy-joe init --from-current
sloppy-joe init --from-current --register
sloppy-joe init --register

#### 작업 입력

| 입력 | 설명 | 기본값 |
|-------|-------------|---------|
| `config` | 설정 파일 경로 또는 HTTPS URL | *(없음)* |
| `dir` | 스캔할 프로젝트 디렉터리 | `.` |
| `type` | 생태계 (`npm`, `pypi`, `cargo`, `go`, `ruby`, `php`, `jvm`, `dotnet`) | 자동 감지 |
| `deep` | 전이 종속성 유사성 검사 활성화 | `false` |
| `paranoid` | 비트플립 변형 활성화 | `false` |
| `args` | 추가 CLI 인수 | *(없음)* |
| `version` | 설치할 sloppy-joe 버전 | `latest` |

#### 예제```yaml
# Minimal — CI-oriented scan, auto-detect ecosystem, no config
- uses: brennhill/[email protected]

# With org config from a URL
- uses: brennhill/[email protected]
  with:
    config: https://raw.githubusercontent.com/yourorg/configs/main/sloppy-joe.json

# Deep scan with paranoid mode
- uses: brennhill/[email protected]
  with:
    config: ${{ secrets.SLOPPY_JOE_CONFIG }}
    deep: true
    paranoid: true

# Scan a subdirectory, pin to a specific version
- uses: brennhill/[email protected]
  with:
    dir: ./packages/api
    version: '1.1.0'

### pre-commit

sloppy-joe는 [pre-commit](https://pre-commit.com) 프레임워크와 함께 작동합니다.
`.pre-commit-config.yaml`에 추가하세요:```yaml
# .pre-commit-config.yaml
repos:
  - repo: https://github.com/brennhill/sloppy-joe
    rev: v1.1.0
    hooks:
      - id: sloppy-joe

또는 프레임워크 없이 간단한 셸 훅을 사용하세요:```bash
#!/bin/sh
sloppy-joe check || exit 1

유사성 검사는 4단계로 실행됩니다.
- **0단계: 범위 스쿼팅** — 로컬 검사, 네트워크 없음. Levenshtein 거리를 통해 알려진 정상 범위/네임스페이스와 비교합니다.
- **1단계: 매니페스트 내부** — 로컬 검사. 동일한 매니페스트의 두 의존성이 서로 변형(mutation)인 경우 플래그를 지정합니다.
- **2단계: 레지스트리 쿼리** — 변형을 생성하고, 레지스트리에 일괄 쿼리하여 존재 여부를 확인한 후 결과를 캐싱합니다(7일 TTL).
- **3단계: 메타데이터 보강** — 일치 항목에 대한 다운로드 수와 게시 날짜를 가져와 보고서에 증거를 추가합니다.

각 변형 생성기는 출력에 태그를 지정하므로, 보고된 검사 유형(예: `similarity/homoglyph`)은 결정적입니다. 여러 생성기가 동일한 후보를 생성하는 경우 가장 심각도가 높은 생성기가 우선합니다.

## CI 신뢰성

sloppy-joe는 불안정한 실패가 허용되지 않는 CI 파이프라인을 위해 설계되었습니다.

**백오프(backoff)를 통한 재시도.** 모든 레지스트리 HTTP 호출은 일시적 오류(5xx, 타임아웃, 연결 오류) 발생 시 지수 백오프(200ms, 400ms, 800ms)로 3회 재시도합니다. 단 한 번의 네트워크 오류로 빌드가 실패하지 않습니다.

**쿼리 오류 시 장애-폐쇄(fail-closed).** 레지스트리 또는 OSV 쿼리가 실패하면, sloppy-joe는 검사를 조용히 건너뛰는 대신 차단 오류 `registry-unreachable`을 발생시킵니다. 더 이상 검사가 차단되기 전에 생태계별 임계값이나 샘플 크기 제한에 의존하지 않습니다.

**유사성 캐시.** 변형 존재 결과는 7일 동안 캐시됩니다. 첫 번째 검사 이후 대부분의 쿼리는 네트워크 호출 없이 캐시에서 처리됩니다. 새 의존성만 레지스트리 쿼리를 트리거합니다.

**잠금 파일 인식 해결.** 지원되는 잠금 파일이 있고 신뢰할 수 있는 경우(`package-lock.json`, `npm-shrinkwrap.json`, `Cargo.lock`, `Gemfile.lock`, Poetry 프로젝트의 `poetry.lock`, uv 프로젝트의 `uv.lock`, `composer.lock`, `gradle.lockfile`, `packages.lock.json`), sloppy-joe는 범위에서 추측하는 대신 잠금 파일에서 정확한 버전을 확인합니다. 완전 해시 잠금된 `requirements*.txt`도 정확한 고정 버전을 제공할 수 있으며, 커밋된 요구 사항 그래프가 자체 `--index-url`과 정확히 허용된 `--extra-index-url` 값을 바인딩할 때 완전히 신뢰됩니다.

## 테스트

테스트 스위트는 유사성 검사, 메타데이터 신호, OSV 동작, 구성 파싱 및 검증, 잠금 파일 해결, 매니페스트 및 잠금 파일 사전 점검 정책, 보고서 형식화, HTTP 재시도 로직을 다룹니다.```bash
cargo test