SSRF 보호 환경 변수
n8n v2.29이 섹션의 상세 내용은 n8n 공식 문서를 참조하세요. SSRF(Server-Side Request Forgery, 서버 측 요청 위조)는 공격자가 선택한 주소로 서버가 HTTP 요청을 보내도록 속이는 공격입니다. SSRF 보호는 기본적으로 꺼져 있습니다.
이 섹션의 상세 내용은 n8n 공식 문서를 참조하세요.
SSRF(Server-Side Request Forgery, 서버 측 요청 위조)는 공격자가 선택한 주소로 서버가 HTTP 요청을 보내도록 속이는 공격입니다. 예를 들어 localhost와 같은 내부 전용 대상, 사설 네트워크 대역, 또는 클라우드 제공업체의 메타데이터 엔드포인트(169.254.169.254)가 그 대상이 될 수 있습니다. 워크플로는 사용자가 제어하는 입력값으로부터 요청 URL을 만들어낼 수 있기 때문에, n8n은 그 입력값에서 비롯된 대상으로 나가는 아웃바운드 요청을 보호할 수 있습니다.
SSRF 보호는 기본적으로 꺼져 있습니다. 이 페이지에서는 이를 켜고 세부적으로 조정하는 변수를 안내합니다.
보호 대상#
| 변수 | 유형 | 기본값 | 설명 |
|---|---|---|---|
N8N_SSRF_PROTECTION_ENABLED |
Boolean | false |
사용자가 제어할 수 있는 대상으로 향하는 요청에 대해 SSRF 보호를 켭니다. |
N8N_SSRF_BLOCKED_IP_RANGES |
String | default |
차단할 CIDR 범위를 쉼표로 구분하여 나열합니다. default 키워드(대소문자 구분 없음)는 n8n에 내장된 기본 세트로 확장됩니다. 자체 범위를 추가하려면 다음과 같이 씁니다: default,100.64.0.0/10. |
N8N_SSRF_ALLOWED_IP_RANGES |
String | - |
허용할 CIDR 범위를 쉼표로 구분하여 나열합니다. 차단 목록보다 우선하므로, 알려진 내부 호스트에 접근할 때 사용합니다. |
N8N_SSRF_ALLOWED_HOSTNAMES |
String | - |
허용할 호스트 이름을 쉼표로 구분하여 나열합니다. 앞에 붙는 *. 와일드카드를 지원합니다. 예를 들어 *.internal.example.com은 중첩된 하위 도메인을 포함한 모든 하위 도메인과 일치하지만, 도메인 자체와는 일치하지 않습니다. 대소문자를 구분하지 않고 일치시킵니다. |
N8N_SSRF_BLOCKED_HOSTNAMES |
String | - |
이름으로 거부할 호스트 이름을 쉼표로 구분하여 나열하며, DNS 확인 전에 검사됩니다. N8N_SSRF_ALLOWED_HOSTNAMES와 동일하게 앞에 붙는 *. 와일드카드와 대소문자 구분 없는 일치를 사용합니다. 허용된 호스트 이름은 항상 차단된 호스트 이름보다 우선합니다. |
N8N_SSRF_DNS_CACHE_MAX_SIZE |
Number | 1048576 |
내부 DNS 확인 캐시의 최대 크기(바이트 단위, 기본값 1MB)입니다. 캐시가 가득 차면 n8n은 가장 오래 사용되지 않은 항목을 제거합니다. |
N8N_SSRF_BLOCKED_IP_RANGES 또는 N8N_SSRF_ALLOWED_IP_RANGES에 잘못된 CIDR 범위를 설정하면 n8n은 경고를 기록하고 해당 범위를 건너뛰므로, 오타가 있어도 인스턴스 시작이 중단되지는 않습니다.
기본적으로 차단되는 항목#
N8N_SSRF_BLOCKED_IP_RANGES에 default가 포함되어 있으면 n8n은 다음 범위를 차단합니다:
- 사설 네트워크(RFC 1918):
10.0.0.0/8,172.16.0.0/12,192.168.0.0/16 - 루프백:
127.0.0.0/8,::1/128 - 링크 로컬(클라우드 메타데이터 포함):
169.254.0.0/16,fe80::/10 - IPv6 고유 로컬:
fc00::/7,fd00::/8 - 예약됨 또는 특수 목적:
0.0.0.0/8,192.0.0.0/24,192.0.2.0/24,198.18.0.0/15,198.51.100.0/24,203.0.113.0/24
n8n이 요청을 평가하는 방식#
n8n은 각 대상을 다음 순서로 검사하며, 처음 일치하는 항목에서 멈춥니다:
- 허용된 호스트 이름: 요청 호스트 이름이
N8N_SSRF_ALLOWED_HOSTNAMES와 일치하면, n8n은 요청을 허용합니다. - 차단된 호스트 이름: 요청 호스트 이름이
N8N_SSRF_BLOCKED_HOSTNAMES와 일치하면, n8n은 요청을 차단합니다. 이 검사는 DNS 확인 전에 실행되므로, n8n은 조회 없이 해당 이름을 거부합니다. 설령 그 이름이 공용 IP로 확인되더라도 마찬가지입니다. - 허용된 IP 범위: 확인된 IP가
N8N_SSRF_ALLOWED_IP_RANGES와 일치하면, n8n은 요청을 허용합니다. - 차단된 IP 범위: 확인된 IP가
N8N_SSRF_BLOCKED_IP_RANGES와 일치하면, n8n은 요청을 차단합니다. - 그 외의 경우: n8n은 요청을 허용합니다.
n8n이 허용 목록을 먼저 검사하기 때문에, 허용 항목은 항상 차단 목록보다 우선합니다.
일반적인 시나리오#
의도적으로 내부 서비스에 접근하기. 워크플로가 내부 호스트를 호출해야 하는 경우, 보호를 끄기보다는 해당 대상만 허용하십시오:
N8N_SSRF_PROTECTION_ENABLED=true
N8N_SSRF_ALLOWED_IP_RANGES=10.20.0.5/32
내부 호스트 이름 허용하기:
N8N_SSRF_ALLOWED_HOSTNAMES=*.svc.cluster.local
기본값보다 더 엄격하게 설정하기. 사용 환경에 맞는 범위를 추가합니다:
N8N_SSRF_BLOCKED_IP_RANGES=default,100.64.0.0/10
이름으로 호스트 이름 거부하기. 확인되는 IP와 무관하게 호스트와 그 모든 하위 도메인을 차단합니다:
N8N_SSRF_BLOCKED_HOSTNAMES=example.com,*.example.com
호스트 이름 차단은 SSRF 강화가 아니라 아웃바운드 트래픽 거버넌스입니다
N8N_SSRF_BLOCKED_HOSTNAMES는 이름으로 거부하므로, 호출자는 여전히 IP 리터럴, 대체 호스트 이름, 또는 DNS 리바인딩을 통해 같은 대상에 접근할 수 있습니다. 이는 알려진 원치 않는 대상을 억제하는 용도로 사용하고, SSRF 보호는 IP 기반 차단 목록에 의존하십시오.
n8n이 요청을 차단하는 경우#
IP로 인해 차단된 요청은 "The request was blocked because it resolves to a restricted IP address"(요청이 제한된 IP 주소로 확인되어 차단되었습니다)라는 오류로 실패합니다. 호스트 이름으로 인해 차단된 요청은 "The request was blocked because the destination hostname is restricted"(대상 호스트 이름이 제한되어 요청이 차단되었습니다)라는 오류로 실패합니다. 두 설명 모두 대상을 명시하고, 사용자에게 n8n 관리자에게 해당 호스트 이름 또는 IP 범위를 허용해 달라고 요청하라고 안내합니다. 요청이 정당하다면 예상되는 대상을 N8N_SSRF_ALLOWED_IP_RANGES 또는 N8N_SSRF_ALLOWED_HOSTNAMES에 추가하십시오.
프로덕션에서 활성화하기 전에 허용 목록을 검토하십시오
보호는 기본적으로 꺼져 있어서 내부 서비스를 호출하는 기존 셀프 호스팅 설정을 손상시키지 않습니다. 이를 켜기 전에, 워크플로에 필요한 내부 호스트 목록을 작성하고 허용 목록에 추가하십시오. 보호를 완전히 끄기보다는 단일 호스트나 호스트 이름과 같이 좁은 범위의 허용 항목을 사용하는 것이 좋습니다.