네트워크 보안 정책 API 레퍼런스

서버의 로컬 방화벽 설정 및 접근 허용 IP 리스트를 프로그래밍 방식으로 제어하는 API를 안내합니다.

📋 개요

이 API 모듈은 GIIP [로컬 가드] 기능을 제어하여, 서버의 입출력 트래픽을 필터링하는 보안 정책을 실시간으로 업데이트합니다.

🔐 인증 및 헤더

모든 요청은 공통 인증 헤더를 포함해야 합니다.

• Header: x-giip-ak: [Your Access Key]
• Header: x-giip-sk: [Your Secret Key]

🚀 주요 API 엔드포인트

1. 서버별 보안 룰 조회 (Get Security Rules)

• URL: POST /api/security/rules/list
• 설명: 특정 서버에 적용된 인바운드/아웃바운드 허용 룰 정보를 조회합니다.
• Request Body:

{
  "serverIsn": 456
}

2. 허용 IP 추가 (Add Allowed IP)

• URL: POST /api/security/rules/add
• 설명: 특정 포트에 접근 가능한 신규 IP 또는 대역을 방화벽 정책에 추가합니다.
• Request Body:

{
  "serverIsn": 456,
  "port": 8080,
  "allowedIp": "1.2.3.4",
  "description": "Dev Team Access"
}

3. 보안 정책 일괄 배포 (Deploy Policy)

• URL: POST /api/security/policy/deploy
• 설명: 특정 프로젝트 소속 모든 서버에 대해 표준 보안 정책을 한꺼번에 적용합니다.
• Request Body:

{
  "projectIsn": 123,
  "policyId": "P-SEC-001"
}

🔍 응답 데이터 예시

{
  "RstVal": 0,
  "RstMsg": "Success",
  "Data": {
    "affectedServers": 15,
    "status": "In Progress"
  }
}

💡 활용 사례

• 동적 IP 화이트리스팅: 재택근무 직원이 VPN 접속 시 자동으로 해당 직원의 현재 IP를 서버 방화벽에 등록합니다.
• 침입 대응 자동화: 보안 관제 시스템에서 공격 IP 탐지 시, 즉시 API를 호출하여 해당 IP를 전사 서버에서 차단합니다.

🛡️ Sk3(고성능 로깅) 활용

보안 정책 수정이나 IP 화이트리스팅과 같은 민감한 인프라 제어 작업 시, 변경 이력의 무결성 보장과 상세한 감사 로그(Audit Log)를 위해 giipApiSk3 엔드포인트를 권장합니다.

• 엔드포인트: https://giipfaw.azurewebsites.net/api/giipApiSk3
• 보안 장점: 정책 업데이트 실패 시 호출자의 상세 환경 정보(IP, UA)와 StackTrace를 즉시 기록하여 침해 사고 시도 여부나 설정 에러의 원인을 신속하게 분석할 수 있습니다.
• 활용 팁: text 명령과 jsondata를 조합하여 복잡한 보안 룰셋을 전송할 때 데이터 유실 없이 안전하게 전반적인 인프라 보안 수준을 관리할 수 있습니다.

🔧 문제 해결

증상	원인	해결
모든 요청이 401/인증 오류로 실패한다	x-giip-ak 또는 x-giip-sk 헤더가 누락되었거나 잘못된 키가 사용됨	두 인증 헤더가 모두 포함되었는지, 발급받은 Access Key/Secret Key가 정확한지 확인합니다
POST /api/security/rules/add 응답의 RstVal이 0이 아니다	serverIsn 누락 또는 allowedIp 형식(IP·대역) 오류	Request Body의 serverIsn, port, allowedIp 값을 규격에 맞게 다시 확인합니다
정책 일괄 배포 후 affectedServers가 0으로 반환된다	projectIsn이 잘못되었거나 해당 프로젝트에 소속된 서버가 없음	올바른 projectIsn을 지정하고 프로젝트에 서버가 등록되어 있는지 확인합니다
복잡한 보안 룰셋 전송 시 데이터가 유실된다	text 명령에 특수문자가 이스케이프되지 않음	giipApiSk3 엔드포인트에서 text와 jsondata를 조합해 파라미터를 안전하게 전송합니다

---

버전: 1.1 최종 업데이트: 2026-04-10 소스 파일: giipv3/public/help/api-network-security.ko.md

---

관련 문서:

• API 결과 코드 가이드 (RstVal)