API 참조

CSD는 도메인, 스크립트, 완화 및 모니터링 관리를 위해 /api/shape/csd/에 전용 API를 제공합니다. CSD는 로드 밸런서 구성 API를 통해 HTTP 로드 밸런서에서도 활성화할 수 있습니다.

인증

모든 API 호출에는 API 토큰이 필요합니다. XC 콘솔의 관리 → 자격 증명 → API 자격 증명에서 생성하세요.

API 자동화 — 환경 설정에 설명된 대로 환경 변수를 설정하세요:

set -a && source .env && set +a

모든 curl 예제는 xTOKENx 플레이스홀더 형식을 사용합니다. 환경 변수로 대체하거나 페이지 상단의 대화형 양식을 사용하세요. 예를 들어, xF5XC_API_TOKENx는 $F5XC_API_TOKEN에 해당합니다.

-H "Authorization: APIToken xF5XC_API_TOKENx"

API 규칙

참고

이 규칙은 모든 F5 Distributed Cloud (F5 XC) 구성 및 CSD API 엔드포인트에 적용됩니다. 이를 이해하면 일반적인 자동화 실수를 방지할 수 있습니다.

응답 본문

• POST는 생성된 객체를 JSON으로 반환합니다.
• PUT 및 DELETE는 HTTP 200에서 빈 \{\}을 반환합니다 — 이는 정상이며 오류가 아닙니다. 빈 응답 본문을 실패로 처리하지 마세요.

목록 vs GET 엔드포인트

목록 엔드포인트(예: /healthchecks, /origin_pools, /protected_domains)와 개별 GET 엔드포인트(예: /healthchecks/\{name\})는 서로 다른 응답 구조를 반환합니다:

엔드포인트 유형	예시 경로	응답 구조
목록	/origin_pools	항목에는 최상위 .name, .namespace, .tenant가 있으며 metadata: null 및 get_spec: null
개별 GET	/origin_pools/\{name\}	객체에는 .metadata.name, .spec.*와 전체 구성이 있음

각각에 올바른 jq 경로를 사용하세요. 예를 들어, 목록 엔드포인트에서 이름을 추출하려면 .items[].metadata.name이 아닌 .items[].name을 사용하세요.

보호된 도메인 식별자

보호된 도메인의 GET 및 DELETE 작업에서 \{name\} 경로 매개변수는 임의의 객체 이름이 아닌 도메인 값 자체(예: bankexample.com)입니다. 이는 이름이 사용자가 선택한 식별자인 다른 F5 XC 객체와 다릅니다.

CSD API 엔드포인트

기본 경로: /api/shape/csd/namespaces/\{namespace\}/

상태 및 초기화

작업	메서드	경로
CSD 활성화	POST	/api/shape/csd/namespaces/system/init
상태 조회	GET	/api/shape/csd/namespaces/\{namespace\}/status
JS 구성 조회	GET	/api/shape/csd/namespaces/\{namespace\}/js_configuration
JS 테스트	POST	/api/shape/csd/namespaces/\{namespace\}/testjs
도메인 업데이트	POST	/api/shape/csd/namespaces/\{namespace\}/update_domains

보호된 도메인

작업	메서드	경로
목록 조회	GET	/api/shape/csd/namespaces/\{namespace\}/protected_domains
조회	GET	/api/shape/csd/namespaces/\{namespace\}/protected_domains/\{name\}
생성	POST	/api/shape/csd/namespaces/\{namespace\}/protected_domains
삭제	DELETE	/api/shape/csd/namespaces/\{namespace\}/protected_domains/\{name\}

감지된 도메인

작업	메서드	경로
감지된 항목 목록 조회	GET	/api/shape/csd/namespaces/\{namespace\}/detected_domains
상세 정보 조회	GET	/api/shape/csd/namespaces/\{namespace\}/domain_details

허용된 도메인

작업	메서드	경로
목록 조회	GET	/api/shape/csd/namespaces/\{namespace\}/allowed_domains
조회	GET	/api/shape/csd/namespaces/\{namespace\}/allowed_domains/\{name\}
생성	POST	/api/shape/csd/namespaces/\{namespace\}/allowed_domains
삭제	DELETE	/api/shape/csd/namespaces/\{namespace\}/allowed_domains/\{name\}

완화된 도메인

작업	메서드	경로
목록 조회	GET	/api/shape/csd/namespaces/\{namespace\}/mitigated_domains
조회	GET	/api/shape/csd/namespaces/\{namespace\}/mitigated_domains/\{name\}
생성	POST	/api/shape/csd/namespaces/\{namespace\}/mitigated_domains
삭제	DELETE	/api/shape/csd/namespaces/\{namespace\}/mitigated_domains/\{name\}

스크립트

작업	메서드	경로
스크립트 목록 조회	POST	/api/shape/csd/namespaces/\{namespace\}/scripts
스크립트 목록 조회 (레거시)	GET	/api/shape/csd/namespaces/\{namespace\}/scripts
스크립트 개요 조회	GET	/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/dashboard
동작 목록 조회	GET	/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/behaviors
네트워크 상호작용 목록 조회	GET	/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/networkInteractions
정당성 업데이트	POST	/api/shape/csd/namespaces/\{namespace\}/scripts/\{script_id\}/justification
정당성 삭제	DELETE	/api/shape/csd/namespaces/\{namespace\}/script/justification/\{justification_id\}
읽음 상태 업데이트	POST	/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/readStatus
영향받은 사용자 목록 조회	POST	/api/shape/csd/namespaces/\{namespace\}/scripts/\{script_id\}/affectedUsers

양식 필드

작업	메서드	경로
양식 필드 목록 조회	GET	/api/shape/csd/namespaces/\{namespace\}/formFields
양식 필드 목록 조회 (POST)	POST	/api/shape/csd/namespaces/\{namespace\}/formFields
양식 필드 조회	GET	/api/shape/csd/namespaces/\{namespace\}/formFields/\{id\}
스크립트별 목록 조회	GET	/api/shape/csd/namespaces/\{namespace\}/scripts/\{id\}/formFields
필드 분석 업데이트	POST	/api/shape/csd/namespaces/\{namespace\}/formFields/analysis

CSD 활성화

테넌트에 대해 CSD를 초기화합니다:

curl -s -X POST \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  -H "Content-Type: application/json" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/system/init"

CSD 상태 조회

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/status" \
  | jq .

보호된 도메인

보호된 도메인 목록 조회

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/protected_domains" \
  | jq .

보호된 도메인 추가

curl -s -X POST \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "name": "my-app",
      "namespace": "xF5XC_NAMESPACEx"
    },
    "spec": {}
  }' \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/protected_domains" \
  | jq .

보호된 도메인 삭제

curl -s -X DELETE \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/protected_domains/my-app"

감지된 도메인

감지된 도메인 목록 조회

쿼리 매개변수: locations (위치별 필터), risk (위험 수준별 필터).

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/detected_domains" \
  | jq .

높은 위험으로 필터링:

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/detected_domains?risk=high" \
  | jq .

도메인 상세 정보 조회

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/domain_details?name=suspicious.example.com" \
  | jq .

스크립트

모든 스크립트 목록 조회

curl -s -X POST \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  -H "Content-Type: application/json" \
  -d '{}' \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/scripts" \
  | jq .

스크립트 개요 조회

SCRIPT_ID="your-script-id"

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/scripts/${SCRIPT_ID}/dashboard" \
  | jq .

스크립트 동작 목록 조회

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/scripts/${SCRIPT_ID}/behaviors" \
  | jq .

네트워크 상호작용 목록 조회

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/scripts/${SCRIPT_ID}/networkInteractions" \
  | jq .

완화

완화된 도메인 추가

curl -s -X POST \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "name": "blocked-domain",
      "namespace": "xF5XC_NAMESPACEx"
    },
    "spec": {}
  }' \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/mitigated_domains" \
  | jq .

완화된 도메인 목록 조회

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/mitigated_domains" \
  | jq .

완화 제거

curl -s -X DELETE \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/mitigated_domains/blocked-domain"

허용된 도메인

허용된 도메인 추가

curl -s -X POST \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "name": "trusted-cdn",
      "namespace": "xF5XC_NAMESPACEx"
    },
    "spec": {}
  }' \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/allowed_domains" \
  | jq .

허용된 도메인 목록 조회

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/allowed_domains" \
  | jq .

허용된 도메인 제거

curl -s -X DELETE \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/allowed_domains/trusted-cdn"

JS 삽입 구성

현재 구성 조회

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/shape/csd/namespaces/xF5XC_NAMESPACEx/js_configuration" \
  | jq .

HTTP 로드 밸런서 CSD 구성

CSD JavaScript 삽입은 /api/config/namespaces/\{namespace\}/http_loadbalancers/\{name\}의 구성 API를 통해 HTTP 로드 밸런서에서 직접 활성화할 수도 있습니다.

로드 밸런서 사양 내의 client_side_defense 필드가 삽입을 제어합니다:

{
  "client_side_defense": {
    "policy": {
      "js_insert_all_pages": {}
    }
  }
}

policy는 다음 중 하나를 허용합니다:

필드	설명
js_insert_all_pages	모든 페이지에 삽입
js_insert_all_pages_except	제외 규칙을 제외한 모든 페이지에 삽입
js_insertion_rules	규칙과 일치하는 페이지에만 삽입
disable_js_insert	삽입하지 않음

로드 밸런서에서 CSD를 비활성화하려면 client_side_defense를 disable_client_side_defense: \{\}로 교체하세요.

로드 밸런서에서 CSD 구성 읽기

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/config/namespaces/xF5XC_NAMESPACEx/http_loadbalancers/xF5XC_LB_NAMEx" \
  | jq '.spec.client_side_defense'

로드 밸런서에서 CSD 활성화

조회, 수정 및 적용:

curl -s \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  "xF5XC_API_URLx/api/config/namespaces/xF5XC_NAMESPACEx/http_loadbalancers/xF5XC_LB_NAMEx" \
  > lb-config.json

jq '.spec |= (
  del(.disable_client_side_defense) |
  .client_side_defense = {
    "policy": {
      "js_insert_all_pages": {}
    }
  }
)' lb-config.json > lb-config-updated.json

curl -s -X PUT \
  -H "Authorization: APIToken xF5XC_API_TOKENx" \
  -H "Content-Type: application/json" \
  -d @lb-config-updated.json \
  "xF5XC_API_URLx/api/config/namespaces/xF5XC_NAMESPACEx/http_loadbalancers/xF5XC_LB_NAMEx" \
  | jq '.spec.client_side_defense'

제외 규칙을 위한 도메인 및 경로 매칭

js_insert_all_pages_except 또는 js_insertion_rules를 사용할 때 각 규칙은 도메인과 경로 조합을 매칭합니다.

도메인 (하나 선택):

필드	예시
any_domain: \{\}	모든 도메인
domain.exact_value	"app.example.com"
domain.suffix_value	".example.com"
domain.regex_value	".*\\.example\\.com"

경로 (하나 선택):

필드	예시
path.path	"/login"
path.prefix	"/checkout"
path.regex	"/user/[0-9]+"

API 참조

• CSD API 참조 — 전체 엔드포인트 문서
• CSD 구성 — 콘솔 구성 가이드
• API 자격 증명 — API 토큰 생성