Laravel Threat Detection

Laravel를 위한 보안 모니터링 및 공격 로깅. SQL 인젝션, XSS, RCE, 디렉터리 트래버설, 봇 스캐너 및 /wp-admin 스타일의 정찰 프로브를 탐지하고 기록합니다 — 모든 악의적인 요청이 전체 애플리케이션 컨텍스트와 함께 데이터베이스에 기록됩니다. 이것은 IDS이며 WAF가 아닙니다: 요청을 차단, 필터링 또는 수정하지 않습니다.

다음과 같은 것을 보고 여기에 오셨나요?```

GET /wp-admin/setup-config.php 404 — on a site that isn't WordPress GET /.env 404 — someone wants your database password GET /?id=1' UNION SELECT password FROM 200 — SQL injection against a real route GET /phpmyadmin/index.php 404 — scanning for an admin panel

그 요청들은 이미 당신의 Laravel 앱에 도달하고 있습니다. 접근 로그에는 URL과 상태 코드만 보이고, 그 외에는 아무것도 없습니다 — 디코딩된 페이로드도, 어떤 라우트가 공격 대상이었는지도, 같은 IP가 이번 시간에 다른 40가지 시도를 했는지도 알 수 없습니다.

이 패키지가 그 질문들에 답합니다. Laravel 10–13 앱 어디에든 넣기만 하면 모든 HTTP 요청을 150개 이상의 공격 패턴과 대조해 스캔하고, 각 일치 항목을 신뢰도로 점수화해 데이터베이스에 기록합니다 — 내장 대시보드, Slack 알림, 지리 정보 보강, fail2ban/차단 목록 내보내기까지 포함해서요. 어떤 요청도 차단되지 않습니다. 자물쇠가 아니라 보안 카메라라고 생각하세요: 누가 당신의 라우트를 탐색하는지, 얼마나 자주, 어떤 기법으로 하는지 정확히 보여줍니다.

> 프로덕션 앱에서 추출해 실제 트래픽으로 검증했습니다. 1,857개의 테스트, Laravel 자체 외 런타임 의존성 없음, 탐지에 인터넷 연결도 필요하지 않습니다.
>
> 업그레이드하시나요? [UPGRADING.md](https://github.com/jay123anta/laravel-threat-detection/blob/main/UPGRADING.md)를 참고하세요. 기여하시나요? [CONTRIBUTING.md](https://github.com/jay123anta/laravel-threat-detection/blob/main/CONTRIBUTING.md)를 참고하세요.

## 1분 이내에 시작하기```bash
composer require jayanta/laravel-threat-detection
php artisan vendor:publish --tag=threat-detection-migrations
php artisan migrate

그런 다음 미들웨어를 web 그룹에 추가하세요 (Laravel 11+에서는 bootstrap/app.php에 한 줄, 또는 Laravel 10에서는 app/Http/Kernel.php에) — 전체 스니펫은 아래 Quick Start에 있습니다. 이게 전부입니다; 탐지가 활성화됩니다.```bash php artisan threat-detection:doctor # confirms it is actually recording

---

## 어디에 적합한가: IDS vs WAF vs 엣지

이 패키지는 **수동적, 애플리케이션 수준 IDS**입니다 — 감시하고 기록할 뿐,
차단하지 않습니다. WAF나 엣지 서비스를 *대체*하는 것이 아니라 *함께* 위치하도록
설계되었습니다. 각 계층은 다른 계층이 볼 수 없는 것을 봅니다:

| | **이 패키지** (앱 IDS) | **WAF** (mod_security, Cloudflare WAF) | **엣지 / CDN** (Cloudflare) |
|---|:---:|:---:|:---:|
| 악성 요청 차단 | ❌ 로그만 기록 | ✅ | ✅ |
| 전체 앱 컨텍스트 (정확한 라우트, 디코딩된 페이로드, 인증된 사용자) | ✅ | ⚠️ 부분적 | ❌ |
| 내장 대시보드 + DB 내 위협 로그 | ✅ | ⚠️ 경우에 따라 다름 | ⚠️ 엣지만 |
| 앱 특화 탐지 (예: Aadhaar / PAN / IFSC PII) | ✅ 사용자 정의 패턴 | ❌ | ❌ |
| 오프라인 작동 / 외부 서비스 불필요 | ✅ | ⚠️ 의존적 | ❌ |
| 트래픽이 앱에 도달하기 전에 차단 | ❌ | ✅ 엣지 | ✅ |
| 설정 | `composer require` 한 번 | 중간–높음 | 낮음–중간 |
| 비용 | 무료, MIT | 경우에 따라 다름 | 무료 티어 + 유료 |

**요약하자면:** 엣지/WAF는 문에 달린 자물쇠이고, 이것은 *내부*의 보안 카메라로,
어떤 라우트에서 누가 얼마나 자주 무엇을 시도하는지 정확히 알려줄 앱 컨텍스트를
갖추고 있습니다. 엣지 계층이 결코 볼 수 없는 데이터로 실제 의사 결정 — fail2ban
차단, 속도 제한, 지역 차단 — 을 내리는 데 활용하세요.

### 의도적으로 아닌 것

- **WAF가 아닙니다.** 요청을 차단, 필터링, 수정하지 않습니다. 강제 적용에는
  Cloudflare, mod_security, 또는 실제 WAF를 사용하세요. (넘겨줄 엣지 계층이
  없나요? [운영자 측 헬퍼](#acting-on-the-data-operator-side-blocking)가
  패키지의 결정을 노출하므로 직접 다섯 줄짜리 차단 미들웨어를 작성할 수
  있습니다 — 강제 적용 코드는 패키지가 아닌 여러분의 것입니다.)
- **안전한 코딩의 대체물이 아닙니다.** 파라미터화된 쿼리, 입력 검증, 출력
  이스케이프가 실제 방어입니다. 이 패키지는 여러분의 코드가 이미 안전하다고
  가정하고 *가시성*을 제공할 뿐, 보호를 제공하지 않습니다.
- **엣지 서비스가 아닙니다.** Cloudflare를 앞에 둘 수 있다면 두세요 — 그런 다음
  엣지 서비스가 볼 수 없는 애플리케이션 수준의 세부 정보를 위해 이것을
  추가하세요.
- **완전한 탐지기가 아니며, 그럴 수도 없습니다.** 패턴 매칭은 *알려진 공격처럼
  보이는* 공격을 잡습니다. 새로운 기법이나, 충분히 재작성된 익숙한 기법은
  로그 없이 통과할 것이며 — 통과했다는 사실조차 알려지지 않습니다. 여기서의
  침묵은 "아무것도 매칭되지 않았다"는 뜻이지, 결코 "아무 일도 일어나지
  않았다"는 뜻이 아닙니다. 이 패키지가 가치를 발휘하는 곳은 공개된 Laravel
  앱에 실제로 도달하는 트래픽의 대부분을 차지하는 대량·저노력 트래픽입니다:
  스캐너, 정찰 프로브, 기성 주입 문자열, 자격 증명 스프레이. 조용한 로그는
  증거의 부재로 취급하되, 부재의 증거로 취급하지 마세요.

### 첫날부터 여러분의 자체 콘텐츠를 탐지할 것으로 예상하세요

튜닝되지 않은 설치본은 정상적인 콘텐츠에도 반응하며, 설치 후가 아니라 설치 전에
이를 알아야 합니다. 이는 가정이 아니라 측정된 결과입니다 — 테스트 스위트가 이
정확한 목록을 고정하여 변동되지 않도록 합니다 ([`LegitimateTrafficCorpusTest`](https://github.com/jay123anta/laravel-threat-detection/blob/main/tests/Feature/LegitimateTrafficCorpusTest.php)):

<!-- noise-floor:start -->
| 완전히 정상적인 요청 | 튜닝되지 않은 설치본이 기록하는 것 |
|---|---|
| 검색창에 입력한 `how to write a UNION SELECT in postgres` | `SQL Injection UNION` / high |
| `<script>window.dataLayer=[];</script>`를 포함한 블로그 게시물 | `XSS Script Tag` / high |
| 붙여넣은 `SELECT * FROM users WHERE id = 1` 오류가 있는 지원 티켓 | `SQLi Variant` / high |
| `../../etc/passwd`가 고전적인 트래버설 페이로드라고 설명하는 문서 | `Directory Traversal` / medium |
| 실제 인도 휴대폰 번호와 PAN을 수집하는 프로필 양식 | `PAN Number Detected` / high |
<!-- noise-floor:end -->

**이 중 어느 것도 버그가 아닙니다.** `<script>`를 포함한 블로그 게시물은 바이트
단위로 저장형 XSS 페이로드이며, `UNION SELECT` 검색은 그 시도와 구별할 수
없습니다. 애플리케이션 컨텍스트 외에는 이들을 구분하는 것이 없으며, 어떤 패턴
엔진도 여러분을 위해 그 컨텍스트를 제공할 수 없습니다.

컨텍스트를 제공하는 것은 한 줄짜리 설정 변경입니다 — `safe_fields`, `safe_paths`,
`content_paths`, 또는 `relaxed` 모드. [오탐 줄이기](#reducing-false-positives)를
참조하세요. **여러분의 앱이 리치 텍스트, 코드 샘플, 또는 검색 쿼리를 받는다면,
출력을 판단하기 전에 그렇게 하세요.** 기본값은 조용하고 불완전하기보다 의도적으로
시끄럽지만 정직합니다: 알려진 매칭을 침묵시키는 것이 결코 발생하지 않은 매칭을
발견하는 것보다 쉽습니다.

### 그래서 실제로 무엇에 사용하나요?

결코 차단하지 않는 탐지기에 대해 가장 흔한 질문입니다. 노력이 증가하는 순서로
네 가지 답이 있습니다:

| 원하는 것 | 사용할 것 | 노력 |
|---|---|---|
| 무엇이 나를 공격하는지 보기 | [대시보드](#dashboard) 또는 `threat-detection:stats` | 없음, 이미 실행 중 |
| 방화벽에서 반복 위반자 차단 | [`threat-detection:export-fail2ban`](#artisan-commands) — cron으로 파이프 | 한 줄 |
| 웹 서버에서 거부 | [`threat-detection:export-blocklist`](#artisan-commands) → nginx/apache 지시문 | 한 줄 |
| 앱 내에서 요청 거부 | [운영자 측 헬퍼](#acting-on-the-data-operator-side-blocking) — `isBlocklisted()`, `isDdosThresholdExceeded()` | 직접 작성한 미들웨어 약 10줄 |
| 실시간으로 대응 | [`ThreatDetected` 이벤트](#threatdetected-event) — Telegram, SIEM, PagerDuty | 리스너 |

패키지는 인텔리전스를 제공하고, 여러분은 거부를 제공합니다. 이 분리는 의도적입니다
— 여러분의 앱에 있는 강제 적용 코드는 읽고, 테스트하고, 끌 수 있는 코드이며,
탐지 버그가 여러분의 사이트를 다운시킬 수 없다는 것을 의미합니다.


### 다른 Laravel 보안 패키지와의 비교

이들은 서로 다른 문제를 해결하며 잘 조합됩니다 — 이 표는 승자를 가리는 것이
아니라 올바른 도구를 고르는 것에 관한 것입니다.

| 패키지 | 하는 일 | 차단? | 사용 시기 |
|---|---|:---:|---|
| **이 패키지** | 모든 요청을 150개 이상의 패턴과 대조하여 스캔하고, 전체 앱 컨텍스트와 함께 로그 기록 | ❌ | 여러분의 앱에 무엇이 시도되는지 *보고* 싶을 때 |
| `spatie/laravel-honeypot` | 스팸 봇을 잡는 숨겨진 양식 필드 | ✅ 양식만 | 스팸이 들어오는 공개 양식이 있을 때 |
| `graham-campbell/security` | 입력에서 XSS 유사 마크업 제거 | ✅ 변경함 | 단순한 입력 정제를 원할 때 |
| `spatie/laravel-csp` | Content-Security-Policy 헤더 전송 | ✅ 브라우저 | 브라우저가 로드하는 것을 제한하고 싶을 때 |
| `laravel/fortify` + 속도 제한 | 인증 스로틀링 및 잠금 | ✅ | 로그인에 대한 무차별 대입 보호가 필요할 때 |
| Cloudflare / mod_security | 엣지 WAF, 앱 전에 차단 | ✅ | 트래픽이 도달하기 전에 중단하고 싶을 때 |