API를 통한 Check Point SandBlast와의 상호 작용

이 기사는 기술에 익숙한 사람들에게 유용할 것입니다. 체크 포인트 파일 에뮬레이션별(위협 에뮬레이션) 및 사전 파일 정리(위협 추출) 그리고 이러한 작업을 자동화하는 방향으로 나아가고 싶어합니다. 체크포인트는 위협 예방 API, 클라우드와 로컬 장치 모두에서 실행되며 기능적으로는 web/smtp/ftp/smb/nfs 트래픽 스트림에서 파일을 확인하는 것과 동일합니다.. 이 기사는 부분적으로 공식 문서의 기사 세트에 대한 저자의 해석이지만 내 운영 경험과 내 예를 바탕으로 합니다. 또한 이 기사에서는 Threat Prevention API 작업을 위한 작성자의 Postman 컬렉션을 찾을 수 있습니다.

기본 약어

Threat Prevention API는 다음 텍스트 값을 통해 API에서 호출되는 세 가지 주요 구성 요소와 함께 작동합니다.

av — 알려진 위협의 시그니처 분석을 담당하는 안티 바이러스 구성 요소입니다.

te - 샌드박스의 파일을 확인하고 에뮬레이션 후 악성/양성 판정을 내리는 위협 에뮬레이션 구성 요소입니다.

추출 - 사용자/시스템에 신속하게 전달하기 위해 사무실 문서를 안전한 형식(잠재적으로 모든 악성 콘텐츠가 제거됨)으로 신속하게 변환하는 역할을 하는 위협 추출 구성 요소입니다.

API 구조 및 주요 제한사항

Threat Prevention API는 4개의 요청만 사용합니다. − 업로드, 쿼리, 다운로드 및 할당량. XNUMX개 요청 모두의 헤더에서 매개변수를 사용하여 API 키를 전달해야 합니다. 권한 부여. 얼핏 보면 구조가 생각보다 단순해 보이지만 관리 API하지만 업로드 및 쿼리 요청의 필드 수와 이러한 요청의 구조는 상당히 복잡합니다. 이는 게이트웨이/샌드박스 보안 정책의 위협 예방 프로필과 기능적으로 비교할 수 있습니다.

현재 Threat Prevention API의 유일한 버전인 1.0이 출시되었습니다. API 호출의 URL에는 다음이 포함되어야 합니다. v1 버전을 지정해야 하는 부분에서 관리 API와 달리 URL에 API 버전을 표시해야 합니다. 그렇지 않으면 요청이 실행되지 않습니다.

다른 구성 요소(te, 추출) 없이 호출되는 경우 안티 바이러스 구성 요소는 현재 md5 해시 합계가 있는 쿼리 요청만 지원합니다. 위협 에뮬레이션 및 위협 추출은 sha1 및 sha256 해시 합계도 지원합니다.

쿼리에서 실수를 하지 않는 것이 매우 중요합니다! 요청은 오류 없이 실행될 수 있지만 완전히 실행될 수는 없습니다. 조금 더 앞을 내다보며 쿼리에 오류/오타가 있는 경우 어떤 일이 발생할 수 있는지 살펴보겠습니다.

보고서(reportss)라는 단어에 오타가 있는 요청

{ "request":  [  

		{	
			"sha256": {{sha256}},
			"features": ["te"] , 
			"te": {
				"images": [
                    {
                        "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
                        "revision": 1
                    }
                ],
                reportss: ["tar", "pdf", "xml"]
            }
		}
	] 
}

응답에는 오류가 없지만 신고 내용에 대한 정보는 전혀 없습니다.

{
  "response": [
    {
      "status": {
        "code": 1001,
        "label": "FOUND",
        "message": "The request has been fully answered."
      },
      "sha256": "9cc488fa6209caeb201678f8360a6bb806bd2f85b59d108517ddbbf90baec33a",
      "file_type": "pdf",
      "file_name": "",
      "features": [
        "te"
      ],
      "te": {
        "trust": 10,
        "images": [
          {
            "report": {
              "verdict": "malicious"
            },
            "status": "found",
            "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
            "revision": 1
          }
        ],
        "score": -2147483648,
        "combined_verdict": "malicious",
        "severity": 4,
        "confidence": 3,
        "status": {
          "code": 1001,
          "label": "FOUND",
          "message": "The request has been fully answered."
        }
      }
    }
  ]
}

하지만 보고서 키에 오타가 없는 요청의 경우

{ "request":  [  

		{	
			"sha256": {{sha256}},
			"features": ["te"] , 
			"te": {
				"images": [
                    {
                        "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
                        "revision": 1
                    }
                ],
                reports: ["tar", "pdf", "xml"]
            }
		}
	] 
}

보고서를 다운로드하기 위한 ID가 이미 포함된 응답을 받았습니다.

{
  "response": [
    {
      "status": {
        "code": 1001,
        "label": "FOUND",
        "message": "The request has been fully answered."
      },
      "sha256": "9cc488fa6209caeb201678f8360a6bb806bd2f85b59d108517ddbbf90baec33a",
      "file_type": "pdf",
      "file_name": "",
      "features": [
        "te"
      ],
      "te": {
        "trust": 10,
        "images": [
          {
            "report": {
              "verdict": "malicious",
              "full_report": "b684066e-e41c-481a-a5b4-be43c27d8b65",
              "pdf_report": "e48f14f1-bcc7-4776-b04b-1a0a09335115",
              "xml_report": "d416d4a9-4b7c-4d6d-84b9-62545c588963"
            },
            "status": "found",
            "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
            "revision": 1
          }
        ],
        "score": -2147483648,
        "combined_verdict": "malicious",
        "severity": 4,
        "confidence": 3,
        "status": {
          "code": 1001,
          "label": "FOUND",
          "message": "The request has been fully answered."
        }
      }
    }
  ]
}

잘못되었거나 만료된 API 키를 보내면 응답으로 403 오류가 발생합니다.

SandBlast API: 클라우드 및 로컬 장치

위협 에뮬레이션 구성 요소(블레이드)가 활성화된 Check Point 장치로 API 요청을 보낼 수 있습니다. 요청 주소로는 장치의 ip/url과 포트 18194를 사용해야 합니다(예: https://10.10.57.19:18194/tecloud/api/v1/파일/쿼리). 또한 장치의 보안 정책이 이 연결을 허용하는지 확인해야 합니다. 기본적으로 로컬 장치에서 API 키를 통한 인증 끄다 요청 헤더의 인증 키가 전혀 전송되지 않을 수 있습니다.

CheckPoint 클라우드에 대한 API 요청은 다음으로 전송되어야 합니다. te.checkpoint.com (예: https://te.checkpoint.com/tecloud/api/v1/파일/쿼리). API 키는 Check Point 파트너 또는 회사 현지 사무소에 문의하여 60일 동안 평가판 라이선스로 얻을 수 있습니다.

로컬 장치에서는 위협 추출이 아직 표준으로 지원되지 않습니다. 위협 예방 API 그리고 사용해야한다 보안 게이트웨이용 위협 예방 API (기사 끝 부분에서 이에 대해 더 자세히 설명하겠습니다).

로컬 장치는 할당량 요청을 지원하지 않습니다.

그렇지 않으면 로컬 장치에 대한 요청과 클라우드에 대한 요청 간에 차이가 없습니다.

업로드 API 호출

사용방법 - POST

전화주소 - https:///tecloud/api/v1/파일/업로드

요청은 에뮬레이션/정리용 파일과 텍스트가 포함된 요청 본문의 두 부분(양식 데이터)으로 구성됩니다.

텍스트 요청은 비워둘 수 없지만 구성을 포함할 수는 없습니다. 요청이 성공하려면 요청에 최소한 다음 텍스트를 보내야 합니다.

업로드 요청에 필요한 최소값

HTTP 포스트

https:///tecloud/api/v1/파일/업로드

헤더 :

권한 부여:

신체

{

"요구": {

}

}

입양 부모로서의 귀하의 적합성을 결정하기 위해 미국 이민국에

입양 부모로서의 귀하의 적합성을 결정하기 위해 미국 이민국에

이 경우 파일은 기본 매개변수에 따라 처리됩니다: 구성요소 - te, OS 이미지 - Win XP 및 Win 7, 보고서를 생성하지 않고.

텍스트 요청의 기본 필드에 대한 설명:

파일 이름 и 파일 유형 파일을 업로드할 때 특별히 유용한 정보는 아니기 때문에 공백으로 남겨두거나 전혀 보내지 않을 수 있습니다. API 응답에서 이러한 필드는 다운로드한 파일의 이름을 기반으로 자동으로 채워지며 캐시의 정보는 여전히 md5/sha1/sha256 해시 양을 사용하여 검색해야 합니다.

file_name 및 file_type이 비어 있는 요청 예시

{

"request": {

"file_name": "",

"file_type": "",

}

}

풍모 — 샌드박스에서 처리할 때 필요한 기능을 나타내는 목록 - av(안티바이러스), te(위협 에뮬레이션), 추출(위협 추출). 이 매개 변수가 전혀 전달되지 않으면 기본 구성 요소인 te(Threat Emulation)만 사용됩니다.

사용 가능한 세 가지 구성 요소를 체크인하려면 API 요청에서 이러한 구성 요소를 지정해야 합니다.

av, te 및 추출을 체크인하는 요청의 예

{ "request":  [  

		{	
			"sha256": {{sha256}},
			"features": ["av", "te", "extraction"]  
		}
	] 
}

te 섹션의 키

형상 — 검사를 수행할 운영 체제의 ID 및 개정 번호가 포함된 사전이 포함된 목록입니다. ID와 개정 번호는 모든 로컬 장치와 클라우드에서 동일합니다.

운영 체제 및 개정 목록

사용 가능한 OS 이미지 ID

개정

이미지 OS 및 애플리케이션

e50e99f3-5963-4573-af9e-e3f4750b55e2

1

마이크로 소프트 윈도우: XP - 32비트 SP3
Office: 2003, 2007
Adobe Acrobat Reader가: 9.0
플래시 플레이어 9r115 및 ActiveX 10.0
자바 런타임: 1.6.0u22

7e6fe36e-889e-4c25-8704-56378f0830df

1

마이크로 소프트 윈도우: 7 - 32비트
Office: 2003, 2007
Adobe Acrobat Reader가: 9.0
플래시 플레이어: 10.2r152(플러그인& ActiveX)
자바 런타임: 1.6.0u0

8d188031-1010-4466-828b-0cd13d4303ff

1

마이크로 소프트 윈도우: 7 - 32비트
Office: 2010
Adobe Acrobat Reader가: 9.4
플래시 플레이어: 11.0.1.152 (플러그인 & ActiveX)
자바 런타임: 1.7.0u0

5e5de275-a103-4f67-b55b-47532918fa59

1

마이크로 소프트 윈도우: 7 - 32비트
Office: 2013
Adobe Acrobat Reader가: 11.0
플래시 플레이어: 15 (플러그인 & ActiveX)
자바 런타임: 1.7.0u9

3ff3ddae-e7fd-4969-818c-d5f1a2be336d

1

마이크로 소프트 윈도우: 7 - 64비트
Office: 2013년 (32비트)
Adobe Acrobat Reader가: 11.0.01
플래시 플레이어: 13 (플러그인 & ActiveX)
자바 런타임: 1.7.0u9

6c453c9b-20f7-471a-956c-3198a868dc92 

 

1 

마이크로 소프트 윈도우: 8.1 - 64비트
Office: 2013년 (64비트)
Adobe Acrobat Reader가: 11.0.10
플래시 플레이어: 18.0.0.160 (플러그인 & ActiveX)
자바 런타임: 1.7.0u9

10b4a9c6-e414-425c-ae8b-fe4dd7b25244 

 

1

마이크로 소프트 윈도우: 10
Office: Professional Plus 2016 en-us  
Adobe Acrobat Reader가: DC 2015 MUI
플래시 플레이어: 20 (플러그인 & ActiveX)
자바 런타임: 1.7.0u9

이미지 키가 전혀 지정되지 않은 경우 Check Point(현재 Win XP 및 Win 7)에서 권장하는 이미지에서 에뮬레이션이 수행됩니다. 이러한 이미지는 성능과 포획률의 최상의 균형을 고려하여 권장됩니다.

보고서 — 파일이 악성인 것으로 판명될 경우 요청하는 보고서 목록입니다. 다음 옵션을 사용할 수 있습니다.

1. 개요 - 에뮬레이션 보고서가 포함된 .tar.gz 아카이브 모두 요청된 이미지(HTML 페이지와 에뮬레이터 OS의 비디오, 네트워크 트래픽 덤프, json 보고서, 비밀번호로 보호된 아카이브의 샘플 자체와 같은 구성 요소 모두). 우리는 답에서 열쇠를 찾고 있습니다 - 요약_보고서 보고서의 후속 다운로드를 위해.

2. PDF - 에뮬레이션에 관한 문서 하나 많은 사람들이 Smart Console을 통해 수신하는 데 익숙한 이미지입니다. 우리는 답에서 열쇠를 찾고 있습니다 - pdf_보고서 보고서의 후속 다운로드를 위해.

3. XML - 에뮬레이션에 관한 문서 하나 보고서의 이후 매개변수 구문 분석에 편리한 이미지입니다. 우리는 답에서 열쇠를 찾고 있습니다 - xml_report 보고서의 후속 다운로드를 위해.

4. 타르 - 에뮬레이션 보고서가 포함된 .tar.gz 아카이브 하나 요청된 이미지(HTML 페이지와 에뮬레이터 OS의 비디오, 네트워크 트래픽 덤프, json 보고서, 비밀번호로 보호된 아카이브의 샘플 자체와 같은 구성 요소 모두). 우리는 답에서 열쇠를 찾고 있습니다 - 전체 보고서 보고서의 후속 다운로드를 위해.

요약 보고서 내용

full_report, pdf_report, xml_report 키는 각 OS의 사전에 있습니다.

{
  "response": [
    {
      "status": {
        "code": 1001,
        "label": "FOUND",
        "message": "The request has been fully answered."
      },
      "sha256": "9e6f07d03b37db0d3902bde4e239687a9e3d650e8c368188c7095750e24ad2d5",
      "file_type": "html",
      "file_name": "",
      "features": [
        "te"
      ],
      "te": {
        "trust": 10,
        "images": [
          {
            "report": {
              "verdict": "malicious",
              "full_report": "8d18067e-b24d-4103-8469-0117cd25eea9",
              "pdf_report": "05848b2a-4cfd-494d-b949-6cfe15d0dc0b",
              "xml_report": "ecb17c9d-8607-4904-af49-0970722dd5c8"
            },
            "status": "found",
            "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
            "revision": 1
          },
          {
            "report": {
              "verdict": "malicious",
              "full_report": "d7c27012-8e0c-4c7e-8472-46cc895d9185",
              "pdf_report": "488e850c-7c96-4da9-9bc9-7195506afe03",
              "xml_report": "e5a3a78d-c8f0-4044-84c2-39dc80ddaea2"
            },
            "status": "found",
            "id": "6c453c9b-20f7-471a-956c-3198a868dc92",
            "revision": 1
          }
        ],
        "score": -2147483648,
        "combined_verdict": "malicious",
        "severity": 4,
        "confidence": 3,
        "status": {
          "code": 1001,
          "label": "FOUND",
          "message": "The request has been fully answered."
        }
      }
    }
  ]
}

그러나 summary_report 키 - 일반적으로 에뮬레이션을 위한 키가 있습니다.

{
  "response": [
    {
      "status": {
        "code": 1001,
        "label": "FOUND",
        "message": "The request has been fully answered."
      },
      "sha256": "d57eadb7b2f91eea66ea77a9e098d049c4ecebd5a4c70fb984688df08d1fa833",
      "file_type": "exe",
      "file_name": "",
      "features": [
        "te"
      ],
      "te": {
        "trust": 10,
        "images": [
          {
            "report": {
              "verdict": "malicious",
              "full_report": "c9a1767b-741e-49da-996f-7d632296cf9f",
              "xml_report": "cc4dbea9-518c-4e59-b6a3-4ea463ca384b"
            },
            "status": "found",
            "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
            "revision": 1
          },
          {
            "report": {
              "verdict": "malicious",
              "full_report": "ba520713-8c0b-4672-a12f-0b4a1575b913",
              "xml_report": "87bdb8ca-dc44-449d-a9ab-2d95e7fe2503"
            },
            "status": "found",
            "id": "6c453c9b-20f7-471a-956c-3198a868dc92",
            "revision": 1
          }
        ],
        "score": -2147483648,
        "combined_verdict": "malicious",
        "severity": 4,
        "confidence": 3,
        "summary_report": "7e7db12d-5df6-4e14-85f3-2c1e29cd3e34",
        "status": {
          "code": 1001,
          "label": "FOUND",
          "message": "The request has been fully answered."
        }
      }
    }
  ]
}

tar와 xml 및 pdf 보고서를 동시에 요청할 수 있으며 요약과 tar 및 xml을 요청할 수 있습니다. 요약 보고서와 PDF를 동시에 요청할 수는 없습니다.

추출 섹션의 키

위협 추출에는 두 개의 키만 사용됩니다.

방법 — pdf(pdf로 변환, 기본적으로 사용됨) 또는 clean(활성 콘텐츠 정리).

추출_부품_코드 - 활성 콘텐츠 제거 코드 목록, 정리 방법에만 적용 가능

파일에서 콘텐츠를 제거하기 위한 코드

암호

상품 설명

1025

연결된 개체

1026

매크로 및 코드

1034

민감한 하이퍼링크

1137

PDF GoToR 작업

1139

PDF 실행 작업

1141

PDF URI 작업

1142

PDF 사운드 액션

1143

PDF 영화 액션

1150

PDF JavaScript 작업

1151

PDF 제출 양식 작업

1018

데이터베이스 쿼리

1019

포함된 개체

1021

빠른 데이터 저장

1017

사용자 정의 속성

1036

통계 속성

1037

요약 속성

정리된 복사본을 다운로드하려면 몇 초 후에 쿼리 요청(아래에서 설명)을 수행하여 요청 텍스트에 파일의 해시 양과 추출 구성 요소를 지정해야 합니다. 쿼리에 대한 응답의 ID인 extract_file_download_id를 사용하여 치료된 파일을 선택할 수 있습니다. 다시 한 번 조금 앞을 내다보며, 정리된 문서를 다운로드하기 위한 ID를 검색하는 요청 및 쿼리 응답의 예를 제공합니다.

extract_file_download_id 키를 검색하는 쿼리 요청

{ "request":  [  

		{	
			"sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
			"features": ["extraction"] , 
			"extraction": {
		        "method": "pdf"
            }
		}
	] 
}

쿼리에 대한 응답(extract_file_download_id 키 찾기)

{
    "response": [
        {
            "status": {
                "code": 1001,
                "label": "FOUND",
                "message": "The request has been fully answered."
            },
            "sha256": "9a346005ee8c9adb489072eb8b5b61699652962c17596de9c326ca68247a8876",
            "file_type": "",
            "file_name": "",
            "features": [
                "extraction"
            ],
            "extraction": {
                "method": "pdf",
                "extract_result": "CP_EXTRACT_RESULT_SUCCESS",
                "extracted_file_download_id": "b5f2b34e-3603-4627-9e0e-54665a531ab2",
                "output_file_name": "kp-20-xls.cleaned.xls.pdf",
                "time": "0.013",
                "extract_content": "Macros and Code",
                "extraction_data": {
                    "input_extension": "xls",
                    "input_real_extension": "xls",
                    "message": "OK",
                    "output_file_name": "kp-20-xls.cleaned.xls.pdf",
                    "protection_name": "Potential malicious content extracted",
                    "protection_type": "Conversion to PDF",
                    "protocol_version": "1.0",
                    "risk": 5.0,
                    "scrub_activity": "Active content was found - XLS file was converted to PDF",
                    "scrub_method": "Convert to PDF",
                    "scrub_result": 0.0,
                    "scrub_time": "0.013",
                    "scrubbed_content": "Macros and Code"
                },
                "tex_product": false,
                "status": {
                    "code": 1001,
                    "label": "FOUND",
                    "message": "The request has been fully answered."
                }
            }
        }
    ]
}

개요

한 번의 API 호출에서는 확인을 위해 하나의 파일만 보낼 수 있습니다.

av 구성 요소에는 키가 있는 추가 섹션이 필요하지 않으며 사전에 지정하는 것으로 충분합니다. 풍모.

쿼리 API 호출

사용방법 - POST

전화주소 - https:///tecloud/api/v1/file/query

다운로드할 파일(업로드 요청)을 보내기 전에 API 서버의 로드를 최적화하기 위해 샌드박스 캐시(쿼리 요청)를 확인하는 것이 좋습니다. API 서버에는 다운로드한 파일에 대한 정보와 결과가 이미 있을 수 있기 때문입니다. 통화는 텍스트 부분으로만 구성됩니다. 요청의 필수 부분은 파일의 sha1/sha256/md5 해시 양입니다. 그건 그렇고, 업로드 요청에 대한 응답으로 얻을 수 있습니다.

쿼리에 필요한 최소값

HTTP 포스트

https:///tecloud/api/v1/file/query

헤더 :

권한 부여:

신체

{

"요구": {

"sha256":

}

}

sha1/md5/sha256 해시 양이 표시되는 업로드 요청에 대한 응답의 예

{
  "response": {
    "status": {
      "code": 1002,
      "label": "UPLOAD_SUCCESS",
      "message": "The file was uploaded successfully."
    },
    "sha1": "954b5a851993d49ef8b2412b44f213153bfbdb32",
    "md5": "ac29b7c26e7dcf6c6fdb13ac0efe98ec",
    "sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd90",
    "file_type": "",
    "file_name": "kp-20-doc.doc",
    "features": [
      "te"
    ],
    "te": {
      "trust": 0,
      "images": [
        {
          "report": {
            "verdict": "unknown"
          },
          "status": "not_found",
          "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
          "revision": 1
        }
      ],
      "score": -2147483648,
      "status": {
        "code": 1002,
        "label": "UPLOAD_SUCCESS",
        "message": "The file was uploaded successfully."
      }
    }
  }
}

쿼리 요청은 해시 양 외에도 이상적으로는 업로드 요청과 동일해야 합니다(또는 앞으로 예정되어 있음). 또는 "이미"(업로드 요청보다 쿼리 요청에 더 적은 수의 필드가 포함되어 있음)여야 합니다. 쿼리 요청에 업로드 요청에 있었던 것보다 더 많은 필드가 포함된 경우 응답에서 필요한 모든 정보를 받지 못할 수 있습니다.

다음은 필수 데이터 중 일부가 발견되지 않은 쿼리에 대한 응답의 예입니다.

{
  "response": [
    {
      "status": {
        "code": 1006,
        "label": "PARTIALLY_FOUND",
        "message": "The request cannot be fully answered at this time."
      },
      "sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd90",
      "file_type": "doc",
      "file_name": "",
      "features": [
        "te",
        "extraction"
      ],
      "te": {
        "trust": 10,
        "images": [
          {
            "report": {
              "verdict": "malicious",
              "pdf_report": "4e9cddaf-03a4-489f-aa03-3c18f8d57a52",
              "xml_report": "9c18018f-c761-4dea-9372-6a12fcb15170"
            },
            "status": "found",
            "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
            "revision": 1
          }
        ],
        "score": -2147483648,
        "combined_verdict": "malicious",
        "severity": 4,
        "confidence": 1,
        "status": {
          "code": 1001,
          "label": "FOUND",
          "message": "The request has been fully answered."
        }
      },
      "extraction": {
        "method": "pdf",
        "tex_product": false,
        "status": {
          "code": 1004,
          "label": "NOT_FOUND",
          "message": "Could not find the requested file. Please upload it."
        }
      }
    }
  ]
}

분야에 주목하라 암호 и 상표. 이러한 필드는 상태 사전에 세 번 나타납니다. 먼저 전역 키 "code": 1006 및 "label": "PARTIALLY_FOUND"를 확인합니다. 다음으로, 이러한 키는 우리가 요청한 각 개별 구성요소(te 및 추출)에 대해 발견됩니다. 그리고 데이터가 발견된 것이 분명하다면 추출을 위한 정보가 없습니다.

위 예의 쿼리는 다음과 같습니다.

{ "request":  [  

		{	
			"sha256": {{sha256}},
			"features": ["te", "extraction"] , 
			"te": {
				"images": [
                    {
                        "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
                        "revision": 1
                    }
                ],
                "reports": [
                    "xml", "pdf"
                ]
            }
		}
	] 
}

추출 구성 요소 없이 쿼리 요청을 보내는 경우

{ "request":  [  

		{	
			"sha256": {{sha256}},
			"features": ["te"] , 
			"te": {
				"images": [
                    {
                        "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
                        "revision": 1
                    }
                ],
                "reports": [
                    "xml", "pdf"
                ]
            }
		}
	] 
}

그러면 답변에 완전한 정보가 포함됩니다(“코드”: 1001, “레이블”: “FOUND”).

{
  "response": [
    {
      "status": {
        "code": 1001,
        "label": "FOUND",
        "message": "The request has been fully answered."
      },
      "sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd90",
      "file_type": "doc",
      "file_name": "",
      "features": [
        "te"
      ],
      "te": {
        "trust": 10,
        "images": [
          {
            "report": {
              "verdict": "malicious",
              "pdf_report": "4e9cddaf-03a4-489f-aa03-3c18f8d57a52",
              "xml_report": "9c18018f-c761-4dea-9372-6a12fcb15170"
            },
            "status": "found",
            "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
            "revision": 1
          }
        ],
        "score": -2147483648,
        "combined_verdict": "malicious",
        "severity": 4,
        "confidence": 1,
        "status": {
          "code": 1001,
          "label": "FOUND",
          "message": "The request has been fully answered."
        }
      }
    }
  ]
}

캐시에 정보가 전혀 없으면 응답은 "label": "NOT_FOUND"입니다.

{
  "response": [
    {
      "status": {
        "code": 1004,
        "label": "NOT_FOUND",
        "message": "Could not find the requested file. Please upload it."
      },
      "sha256": "313c0feb009356495b7f4a60e96737120beb30e1912c6d866218cee830aebd91",
      "file_type": "",
      "file_name": "",
      "features": [
        "te"
      ],
      "te": {
        "trust": 0,
        "images": [
          {
            "report": {
              "verdict": "unknown"
            },
            "status": "not_found",
            "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
            "revision": 1
          }
        ],
        "score": -2147483648,
        "status": {
          "code": 1004,
          "label": "NOT_FOUND",
          "message": "Could not find the requested file. Please upload it."
        }
      }
    }
  ]
}

한 번의 API 호출로 검증을 위해 여러 해시 금액을 한 번에 보낼 수 있습니다. 응답은 요청에서 전송된 것과 동일한 순서로 데이터를 반환합니다.

여러 sha256 금액이 포함된 쿼리 요청 예시

{ "request":  [  

		{	
			"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81"
        },
        		{	
			"sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82"
        }
	] 
}

여러 sha256 금액이 포함된 쿼리에 대한 응답

{
  "response": [
    {
      "status": {
        "code": 1001,
        "label": "FOUND",
        "message": "The request has been fully answered."
      },
      "sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd81",
      "file_type": "dll",
      "file_name": "",
      "features": [
        "te"
      ],
      "te": {
        "trust": 10,
        "images": [
          {
            "report": {
              "verdict": "malicious"
            },
            "status": "found",
            "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
            "revision": 1
          }
        ],
        "score": -2147483648,
        "combined_verdict": "malicious",
        "severity": 4,
        "confidence": 3,
        "status": {
          "code": 1001,
          "label": "FOUND",
          "message": "The request has been fully answered."
        }
      }
    },
    {
      "status": {
        "code": 1004,
        "label": "NOT_FOUND",
        "message": "Could not find the requested file. Please upload it."
      },
      "sha256": "b84531d3829bf6131655773a3863d6b16f6389b7f4036aef9b81c0cb60e7fd82",
      "file_type": "",
      "file_name": "",
      "features": [
        "te"
      ],
      "te": {
        "trust": 0,
        "images": [
          {
            "report": {
              "verdict": "unknown"
            },
            "status": "not_found",
            "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
            "revision": 1
          }
        ],
        "score": -2147483648,
        "status": {
          "code": 1004,
          "label": "NOT_FOUND",
          "message": "Could not find the requested file. Please upload it."
        }
      }
    }
  ]
}

쿼리 요청에서 한 번에 여러 해시 합계를 요청하는 것도 API 서버 성능에 유익한 영향을 미칩니다.

API 호출 다운로드

사용방법 - POST (문서에 따르면), 바로 또한 작동합니다(더 논리적으로 보일 수 있음).

전화주소 - https:///tecloud/api/v1/file/download?id=

헤더에는 API 키가 전달되어야 하며 요청 본문은 비어 있으며 다운로드 ID는 URL 주소로 전달됩니다.

쿼리 요청에 대한 응답으로 에뮬레이션이 완료되고 파일 다운로드 시 보고서를 요청한 경우 보고서 다운로드용 ID가 표시됩니다. 정리된 사본을 요청하는 경우 정리된 문서를 다운로드하려면 ID를 찾아야 합니다.

전체적으로 로드할 id 값이 포함된 쿼리에 대한 응답의 키는 다음과 같습니다.

• 요약_보고서

• 전체 보고서

• pdf_보고서

• xml_report

• extract_file_download_id

물론, 쿼리 요청에 대한 응답으로 이러한 키를 받으려면 요청에 지정하거나(보고서의 경우) 추출 기능을 사용하여 요청해야 한다는 것을 기억해야 합니다(정리된 문서의 경우).

할당량 API 호출

사용방법 - POST

전화주소 - https:///tecloud/api/v1/file/quota

클라우드에 남은 할당량을 확인하려면 할당량 쿼리를 사용하세요. 요청 본문이 비어 있습니다.

할당량 요청에 대한 응답 예시

{
  "response": [
    {
      "remain_quota_hour": 1250,
      "remain_quota_month": 10000000,
      "assigned_quota_hour": 1250,
      "assigned_quota_month": 10000000,
      "hourly_quota_next_reset": "1599141600",
      "monthly_quota_next_reset": "1601510400",
      "quota_id": "TEST",
      "cloud_monthly_quota_period_start": "1421712300",
      "cloud_monthly_quota_usage_for_this_gw": 0,
      "cloud_hourly_quota_usage_for_this_gw": 0,
      "cloud_monthly_quota_usage_for_quota_id": 0,
      "cloud_hourly_quota_usage_for_quota_id": 0,
      "monthly_exceeded_quota": 0,
      "hourly_exceeded_quota": 0,
      "cloud_quota_max_allow_to_exceed_percentage": 1000,
      "pod_time_gmt": "1599138715",
      "quota_expiration": "0",
      "action": "ALLOW"
    }
  ]
}

보안 게이트웨이용 위협 예방 API

이 API는 Threat Prevention API 이전에 개발되었으며 로컬 장치 전용입니다. 현재로서는 Threat Extraction API가 필요한 경우에만 유용할 수 있습니다. 위협 에뮬레이션의 경우 일반 위협 예방 API를 사용하는 것이 좋습니다. 켜려면 SG용 TP API 다음 단계를 수행하는 데 필요한 API 키를 구성합니다. sk113599. 6b단계에 주의를 기울이고 페이지의 접근성을 확인하는 것이 좋습니다. https://<IPAddressofSecurityGateway>/UserCheck/TPAPI 결과가 부정적일 경우 추가 구성이 의미가 없기 때문입니다. 모든 API 호출은 이 URL로 전송됩니다. 호출 유형(업로드/쿼리)은 호출 본문 키에서 규제됩니다. 요청_이름. 또한 필수 키는 다음과 같습니다. - api_key (구성 프로세스 중에 이를 기억해야 함) 및 프로토콜_버전 (현재 최신 버전은 1.1입니다.) 이 API에 대한 공식 문서는 다음에서 찾을 수 있습니다. sk137032. 상대적인 장점은 파일이 base64 텍스트 문자열로 전송되기 때문에 여러 파일을 로드할 때 에뮬레이션을 위해 한 번에 보낼 수 있다는 것입니다. base64에서 파일을 인코딩/디코딩하려면 데모 목적으로 Postman의 온라인 변환기를 사용할 수 있습니다. 예를 들면 다음과 같습니다. https://base64.guru. 실용적인 목적으로 코드를 작성할 때 내장된 인코딩 및 디코딩 메서드를 사용해야 합니다.

이제 기능을 자세히 살펴보겠습니다. te и 추출 이 API에서.

부품용 te 사전 제공 te_options 업로드/쿼리 요청에서 이 요청의 키는 다음의 te 키와 완전히 일치합니다. 위협 예방 API.

보고서가 포함된 Win10의 파일 에뮬레이션 요청 예시

{
"request": [{
    "protocol_version": "1.1",
    "api_key": "<api_key>",
    "request_name": "UploadFile",
    "file_enc_data": "<base64_encoded_file>",
    "file_orig_name": "<filename>",
    "te_options": {
        "images": [
                {
                    "id": "10b4a9c6-e414-425c-ae8b-fe4dd7b25244",
                    "revision": 1
                }
            ],
        "reports": ["summary", "xml"]
    }
    }
    ]
}

부품용 추출 사전 제공 스크럽 옵션. 이 요청은 치료 방법을 지정합니다. 즉, PDF로 변환, 활성 콘텐츠 지우기, 위협 예방 프로필(프로필 이름이 표시됨)에 따라 모드 선택 등이 있습니다. 파일에 대한 추출 API 요청에 응답할 때 가장 좋은 점은 해당 요청에 대한 응답으로 base64 암호화된 문자열로 정리된 복사본을 얻을 수 있다는 것입니다. 문서)

파일 지우기 요청의 예

    {
	"request": [{
		"protocol_version": "1.1",
		"api_key": "<API_KEY>",
		"request_name": "UploadFile",
		"file_enc_data": "<base64_encoded_file>",
		"file_orig_name": "hi.txt",
		"scrub_options": {
			"scrub_method": 2
		}
	}]
}

요청에 응답

{
	"response": [{
		"protocol_version": "1.1",
		"src_ip": "<IP_ADDRESS>",
		"scrub": {
			"file_enc_data": "<base64_encoded_converted_to_PDF_file>",
			"input_real_extension": "js",
			"message": "OK",
			"orig_file_url": "",
			"output_file_name": "hi.cleaned.pdf",
			"protection_name": "Extract potentially malicious content",
			"protection_type": "Conversion to PDF",
			"real_extension": "txt",
			"risk": 0,
			"scrub_activity": "TXT file was converted to PDF",
			"scrub_method": "Convert to PDF",
			"scrub_result": 0,
			"scrub_time": "0.011",
			"scrubbed_content": ""
		}
	}]
} 

명확한 사본을 얻기 위해 필요한 API 요청 수가 적다는 사실에도 불구하고 이 옵션은 다음에서 사용된 양식 데이터 요청보다 덜 선호되고 편리합니다. 위협 예방 API.

우편 배달부 컬렉션

가장 일반적인 API 요청을 나타내는 위협 예방 API와 보안 게이트웨이용 위협 예방 API 모두에 대해 Postman에서 컬렉션을 만들었습니다. 서버 ip/url API 및 키가 자동으로 요청으로 대체되고 sha256 해시 양이 파일 다운로드 후 기억되도록 컬렉션 내부에 세 가지 변수가 생성되었습니다(컬렉션 설정으로 이동하여 찾을 수 있습니다). 편집 -> 변수): te_api (필수), api_key (로컬 장치에서 TP API를 사용하는 경우를 제외하고 필수 입력), sha256(비워 두세요. SG용 TP API에서는 사용되지 않음).

Threat Prevention API용 Postman 컬렉션 다운로드

Security Gateway API용 위협 예방을 위한 Postman 컬렉션 다운로드

사용 예

커뮤니티에서 메이트 확인 Python으로 작성된 스크립트는 다음을 통해 원하는 디렉터리의 파일을 확인하는 것으로 제공됩니다. TP API과 SG용 TP API. Threat Prevention API와의 상호 작용을 통해 파일 검색 기능이 크게 확장되었습니다. 이제 여러 플랫폼의 파일을 한 번에 검색할 수 있기 때문입니다(체크인). 바이러스토탈 API, Check Point 샌드박스에서) 네트워크 트래픽에서 파일을 받을 뿐만 아니라 모든 네트워크 드라이브, 예를 들어 CRM 시스템에서도 파일을 가져옵니다.

출처 : habr.com