본문 바로가기
WIKI 기술 지식 베이스

Source API

원문 보기 위키 갱신

출처: 문서

본문

Source API

위협 인텔리전스 Source API는 위협 인텔리전스 소스 구성과 관련된 작업에 대한 정보를 업데이트하고 반환해요.

위협 인텔리전스 소스 생성 또는 업데이트

위협 인텔리전스 소스를 생성하거나 업데이트하고, 해당 소스에서 침해 지표(IOC)를 로드해요.

S3_CUSTOM 타입과 IOC_UPLOAD 타입의 소스를 생성할 수 있어요. URL_DOWNLOAD 타입은 OpenSearch가 자동으로 생성하는 내장 피드 전용이므로 이 API로는 생성할 수 없어요. 자세한 내용은 URL_DOWNLOAD 타입 소스를 참고하세요.

엔드포인트

POST _plugins/_security_analytics/threat_intel/sources
PUT _plugins/_security_analytics/threat_intel/sources/{source_id}

요청 본문 필드

필드 타입 설명
type String 위협 인텔리전스 소스의 타입이에요. 유효한 값은 S3_CUSTOM과 IOC_UPLOAD예요.
name String 위협 인텔리전스 소스의 이름이에요.
format String STIX2 같은 위협 인텔리전스 데이터의 포맷이에요.
description String 위협 인텔리전스 소스에 대한 설명이에요.
enabled Boolean 소스에서 IOC를 예약된 일정에 따라 새로 고치는 기능이 활성화되어 있는지를 나타내요.
ioc_types Array of strings 소스가 지원하는 IOC의 STIX2 타입이에요. 예를 들어 hashes, domain-name, ipv4-addr, ipv6-addr 등이 있어요.
source Object 위협 인텔리전스 데이터의 소스 정보예요.
source.ioc_upload Object IOC 업로드에 대한 정보예요. IOC_UPLOAD 타입에 적용돼요.
source.ioc_upload.file_name String IOC가 담긴 파일의 이름이에요. 예를 들어 test 같은 값이에요. IOC_UPLOAD 타입에 적용돼요.
source.ioc_upload.iocs Array of objects STIX2 형식의 IOC 목록이에요. IOC_UPLOAD 타입에 적용돼요.
source_config.source.s3 Object Amazon Simple Storage Service(Amazon S3) 소스에 대한 정보예요. S3_CUSTOM 타입에 적용돼요.
source_config.source.s3.bucket_name String S3 버킷의 이름이에요. 예를 들어 threat-intel-s3-test-bucket 같은 값이에요. S3_CUSTOM 타입에 적용돼요.
source_config.source.s3.object_key String S3 버킷에 있는 객체의 키예요. 예를 들어 alltypess3object 같은 값이에요. S3_CUSTOM 타입에 적용돼요.
source_config.source.s3.region String S3 버킷이 위치한 AWS 리전이에요. 예시: us-west-2. S3_CUSTOM 타입에 적용돼요.
source_config.source.s3.role_arn String S3 버킷에 접근하는 데 사용되는 역할의 Amazon Resource Name(ARN)이에요. 예를 들어 arn:aws:iam::248279774929:role/threat_intel_s3_test_role 같은 값이에요. S3_CUSTOM 타입에 적용돼요.
source_config.source.url_download Object IOC를 다운로드하는 URL에 대한 정보예요. URL_DOWNLOAD 타입에 적용돼요.
source_config.source.url_download.url String IOC를 다운로드하는 URL이에요. http와 https 프로토콜만 지원해요. URL_DOWNLOAD 타입에 적용돼요.
source_config.source.url_download.feed_format String 다운로드한 피드의 포맷이에요. 지원되는 유일한 값은 csv예요. URL_DOWNLOAD 타입에 적용돼요.
source_config.source.url_download.has_csv_header_field Boolean CSV 파일의 첫 행이 헤더 행인지 여부예요. 기본값은 false예요. URL_DOWNLOAD 타입에 적용돼요.
source_config.source.url_download.csv_ioc_value_colum_num Integer IOC 값이 들어 있는 CSV 열의 0부터 시작하는 인덱스예요. URL_DOWNLOAD 타입에 적용돼요.

IOC 필드(STIX2)

다음 필드는 ioc_types 옵션을 수정해요.

필드 타입 설명
id String IOC의 고유 식별자예요. 예를 들어 1 같은 값이에요.
name String 사람이 읽기 쉬운 IOC 이름이에요. 예를 들어 ioc-name 같은 값이에요.
type String IOC의 타입이에요. 예를 들어 hashes 같은 값이에요.
value String IOC의 값이에요. gof 같은 해시 값이 될 수 있어요.
severity String IOC의 심각도 수준이에요. 예시: thvvz.
created Integer/String IOC가 생성된 시점을 나타내는 타임스탬프예요. UNIX epoch 형식 또는 ISO_8601 형식, 예를 들어 1719519073이나 2024-06-20T01:06:20.562008Z 같은 값이에요.
modified Integer/String IOC가 마지막으로 수정된 시점을 나타내는 타임스탬프예요. UNIX epoch 형식 또는 ISO_8601 형식, 예를 들어 1719519073이나 2024-06-20T01:06:20.562008Z. 같은 값이에요.
description String IOC에 대한 설명이에요.
labels Array of strings IOC와 연관된 라벨이나 태그예요.
feed_id String IOC가 속한 피드의 고유 식별자예요.
spec_version String IOC에 사용된 스펙 버전이에요.
version Integer IOC의 버전 번호예요.

응답 본문 필드

필드 데이터 타입 설명
_id String 위협 인텔리전스 소스의 고유 식별자예요.
_version Integer 위협 인텔리전스 소스의 버전 번호예요.
source_config Object 위협 인텔리전스 소스의 구성 세부 정보예요.
source_config.name String 위협 인텔리전스 소스의 이름이에요.
source_config.format String 위협 인텔리전스 데이터의 포맷이에요.
source_config.type String 위협 인텔리전스 소스의 타입이에요.
source_config.ioc_types Array of strings 소스가 지원하는 IOC 타입이에요.
source_config.description String 위협 인텔리전스 소스에 대한 설명이에요.
source_config.created_by_user String or null 위협 인텔리전스 소스를 생성한 사용자예요.
source_config.created_at String (DateTime) 위협 인텔리전스 소스가 생성된 날짜와 시간이에요.
source_config.source Object 위협 인텔리전스 데이터의 소스에 대한 정보를 담고 있어요.
source_config.source.ioc_upload Object IOC 업로드에 대한 정보예요.
source_config.source.ioc_upload.file_name String 업로드된 파일의 이름이에요. 예시: test.
source_config.source.ioc_upload.iocs Array of objects IOC 업로드에 대한 추가 정보예요. IOC가 성공적으로 저장되면 빈 배열로 표시돼요.
source_config.enabled Boolean 위협 인텔리전스 소스가 활성화되어 있는지를 나타내요.
source_config.enabled_time String or null 소스가 활성화된 날짜와 시간이에요.
source_config.last_update_time String (DateTime) 위협 인텔리전스 소스가 마지막으로 업데이트된 날짜와 시간이에요.
source_config.schedule String or null 위협 인텔리전스 소스의 일정이에요.
source_config.state String 위협 인텔리전스 소스의 현재 상태예요.
source_config.refresh_type String 소스에 적용되는 새로 고침 유형이에요.
source_config.last_refreshed_user String or null 소스를 마지막으로 새로 고친 사용자예요.
source_config.last_refreshed_time String (DateTime) 소스가 마지막으로 새로 고쳐진 날짜와 시간이에요.

요청 예제

다음 요청 예제는 Source API를 사용하는 방법을 보여줘요.

IOC_UPLOAD 타입

POST _plugins/_security_analytics/threat_intel/sources/
{
  "type": "IOC_UPLOAD",
  "name": "my_custom_feed",
  "format": "STIX2",
  "description": "this is the description",
  "store_type": "OS",
  "enabled": "false",
  "ioc_types": [
    "hashes"
  ],
  "source": {
    "ioc_upload": {
      "file_name": "test",
      "iocs": [
        {
          "id": "1",
          "name": "uldzafothwgik",
          "type": "hashes",
          "value": "gof",
          "severity": "thvvz",
          "created": 1719519073,
          "modified": 1719519073,
          "description": "first one here",
          "labels": [
            "ik"
          ],
          "feed_id": "jl",
          "spec_version": "gavvnespe",
          "version": -4356924786557562654
        },
        {
          "id": "2",
          "name": "uldzafothwgik",
          "type": "hashes",
          "value": "example-has00001",
          "severity": "thvvz",
          "created": "2024-06-20T01:06:20.562008Z",
          "modified": "2024-06-20T02:06:20.56201Z",
          "description": "first one here",
          "labels": [
            "ik"
          ],
          "feed_id": "jl",
          "spec_version": "gavvnespe",
          "version": -4356924786557562654
        }
      ]
    }
  }
}

{% include copy-curl.html %}

S3_CUSTOM 타입 소스

POST _plugins/_security_analytics/threat_intel/sources/
{
 "type": "S3_CUSTOM",
 "name": "example-ipv4-from-SAP-account",
 "format": "STIX2",
 "store_type": "OS",
 "enabled": "true",
 "schedule": {
  "interval": {
   "start_time": 1717097122,
   "period": "10",
   "unit": "DAYS"
  }
 },
 "source": {
  "s3": {
   "bucket_name": "threat-intel-s3-test-bucket",
   "object_key": "alltypess3object",
   "region": "us-west-2",
   "role_arn": "arn:aws:iam::248279774929:role/threat_intel_s3_test_role"
  }
 },
 "ioc_types": [
  "domain-name",
  "ipv4-addr"
 ]
}

{% include copy-curl.html %}

응답 예제

다음 응답 예제는 요청이 성공했을 때 OpenSearch가 반환하는 내용을 보여줘요.

IOC_UPLOAD 타입

{
  "_id": "2c0u7JAB9IJUg27gcjUp",
  "_version": 2,
  "source_config": {
    "name": "my_custom_feed",
    "format": "STIX2",
    "type": "IOC_UPLOAD",
    "ioc_types": [
      "hashes"
    ],
    "description": "this is the description",
    "created_by_user": null,
    "created_at": "2024-07-25T23:16:25.257697Z",
    "source": {
      "ioc_upload": {
        "file_name": "test",
        "iocs": []
      }
    },
    "enabled": false,
    "enabled_time": null,
    "last_update_time": "2024-07-25T23:16:26.011774Z",
    "schedule": null,
    "state": "AVAILABLE",
    "refresh_type": "FULL",
    "last_refreshed_user": null,
    "last_refreshed_time": "2024-07-25T23:16:25.522735Z"
  }
}

S3_CUSTOM 타입 소스

{
 "id": "rGO5zJABLVyN2kq1wbFS",
 "version": 206,
 "name": "example-ipv4-from-SAP-account",
 "format": "STIX2",
 "type": "S3_CUSTOM",
 "ioc_types": [
  "domain-name",
  "ipv4-addr"
 ],
 "created_by_user": {
  "name": "admin",
  "backend_roles": [],
  "roles": [
   "security_manager",
   "all_access"
  ],
  "custom_attribute_names": []
 },
 "created_at": "2024-07-19T20:40:44.114Z",
 "source": {
  "s3": {
   "bucket_name": "threat-intel-s3-test-bucket",
   "object_key": "alltypess3object",
   "region": "us-west-2",
   "role_arn": "arn:aws:iam::248279774929:role/threat_intel_s3_test_role"
  }
 },
 "enabled": true,
 "enabled_time": "2024-07-19T20:40:44.114Z",
 "last_update_time": "2024-07-25T20:58:18.213Z",
 "schedule": {
  "interval": {
   "start_time": 1717097122,
   "period": 10,
   "unit": "Days"
  }
 },
 "state": "AVAILBLE",
 "refresh_type": "FULL",
 "last_refreshed_user": {
  "name": "admin",
  "backend_roles": [],
  "roles": [
   "security_manager",
   "all_access"
  ],
  "custom_attribute_names": [],
  "user_requested_tenant": null
 },
 "last_refreshed_time": "2024-07-25T20:58:17.131Z"
}

URL_DOWNLOAD 타입 소스

URL_DOWNLOAD 소스는 HTTP 또는 HTTPS URL에서 IOC를 다운로드해요. OpenSearch는 내장 위협 인텔리전스 피드를 위해 이런 소스를 자동으로 생성하기 때문에 Source API로는 생성할 수 없어요. POST 요청에서 URL_DOWNLOAD를 지정하면 다음과 같은 오류가 반환돼요:

URL_DOWNLOAD source type cannot be created via the REST API. It is reserved for internal use only.

클러스터에 있는 URL_DOWNLOAD 소스를 나열하려면 타입으로 검색해 보세요:

POST _plugins/_security_analytics/threat_intel/sources/_search
{
  "query": {
    "match": {
      "source_config.type": "URL_DOWNLOAD"
    }
  }
}

{% include copy-curl.html %}

응답의 source.url_download 객체는 피드를 설명해요:

{
  "_id": "alienvault_reputation_ip_database",
  "_version": 2,
  "source_config": {
    "name": "Alienvault IP Reputation",
    "format": "STIX2",
    "type": "URL_DOWNLOAD",
    "description": "Alienvault IP Reputation threat intelligence feed managed by AlienVault",
    "created_by_user": null,
    "source": {
      "url_download": {
        "url": "https://reputation.alienvault.com/reputation.generic",
        "feed_format": "csv",
        "has_csv_header_field": false,
        "csv_ioc_value_colum_num": 0
      }
    },
    "enabled": true,
    "enabled_for_scan": true,
    "ioc_types": [
      "ipv4-addr"
    ]
  }
}

URL_DOWNLOAD 소스에서는 csv 피드 포맷만 지원돼요. 다른 포맷으로 구성된 소스는 새로 고침에 실패하며 unsupported feed format for url download 오류가 발생해요. {: .note}

URL_DOWNLOAD 소스 활성화 또는 비활성화

URL_DOWNLOAD 소스는 내장 소스이기 때문에 변경할 수 있는 필드는 피드를 활성화하거나 비활성화하는 enabled_for_scan뿐이에요. 다른 필드를 변경하는 업데이트 요청은 Unsupported Threat intel Source Config Type passed 오류를 반환해요. 요청에는 schedule 필드를 반드시 포함해야 해요. 그렇지 않으면 요청이 유효성 검사에 실패해요.

다음 요청은 내장 피드를 비활성화해요:

PUT _plugins/_security_analytics/threat_intel/sources/alienvault_reputation_ip_database
{
  "type": "URL_DOWNLOAD",
  "name": "Alienvault IP Reputation",
  "format": "STIX2",
  "description": "Alienvault IP Reputation threat intelligence feed managed by AlienVault",
  "schedule": {
    "interval": {
      "start_time": 1786030387187,
      "period": 1,
      "unit": "DAYS"
    }
  },
  "source": {
    "url_download": {
      "url": "https://reputation.alienvault.com/reputation.generic",
      "feed_format": "csv",
      "has_csv_header_field": false,
      "csv_ioc_value_colum_num": 0
    }
  },
  "ioc_types": [
    "ipv4-addr"
  ],
  "enabled_for_scan": false
}

{% include copy-curl.html %}

피드를 다시 활성화하려면 enabled_for_scan을 true로 설정해서 같은 요청을 보내면 돼요.

URL_DOWNLOAD 소스는 삭제할 수 없어요. 삭제 요청을 보내면 Cannot delete built-in tif source config 오류가 반환돼요. {: .note}

위협 인텔리전스 소스 구성 세부 정보 조회

위협 인텔리전스 소스의 구성 세부 정보를 조회해요.

엔드포인트

GET /_plugins/_security_analytics/threat_intel/sources/{source-id}

요청 예제

GET /_plugins/_security_analytics/threat_intel/sources/{source-id}

{% include copy-curl.html %}

응답 예제

{
  "_id": "a-jnfjkAF_uQjn8Weo4",
  "_version": 2,
  "source_config": {
    "name": "my_custom_feed_2",
    "format": "STIX2",
    "type": "S3_CUSTOM",
    "ioc_types": [
      "ipv4_addr",
      "hashes"
    ],
    "description": "this is the description",
    "created_by_user": null,
    "created_at": "2024-06-27T00:52:56.373Z",
    "source": {
      "s3": {
        "bucket_name": "threat-intel-s3-test-bucket",
        "object_key": "bd",
        "region": "us-west-2",
        "role_arn": "arn:aws:iam::540654354201:role/threat_intel_s3_test_role"
      }
    },
    "enabled": true,
    "enabled_time": "2024-06-27T00:52:56.373Z",
    "last_update_time": "2024-06-27T00:52:57.824Z",
    "schedule": {
      "interval": {
        "start_time": 1717097122,
        "period": 1,
        "unit": "Days"
      }
    },
    "state": "AVAILABLE",
    "refresh_type": "FULL",
    "last_refreshed_user": null,
    "last_refreshed_time": "2024-06-27T00:52:56.533Z"
  }
}

위협 인텔리전스 소스 검색

검색 쿼리를 기준으로 일치하는 위협 인텔리전스 소스를 검색해요. 요청 본문에는 검색 쿼리가 필요해요. 쿼리 옵션에 대한 자세한 내용은 Query DSL을 참고하세요.

엔드포인트

POST /_plugins/_security_analytics/threat_intel/sources/_search

요청 예제

POST /_plugins/_security_analytics/threat_intel/sources/_search
{
    "query": {
        "match": {
            "source_config.type": "S3_CUSTOM"
        }
    }
}

{% include copy-curl.html %}

응답 예제

{
    "took": 20,
    "timed_out": false,
    "_shards": {
        "total": 1,
        "successful": 1,
        "skipped": 0,
        "failed": 0
    },
    "hits": {
        "total": {
            "value": 1,
            "relation": "eq"
        },
        "max_score": 1.0,
        "hits": [
            {
                "_index": ".opensearch-sap--job",
                "_id": "YEAuV5ABx0lQn6qhY5C1",
                "_version": 2,
                "_seq_no": 1,
                "_primary_term": 1,
                "_score": 1.0,
                "_source": {
                    "source_config": {
                        "name": "my_custom_feed_2",
                        "format": "STIX2",
                        "type": "S3_CUSTOM",
                        "description": "this is the description",
                        "created_by_user": null,
                        "source": {
                            "s3": {
                                "bucket_name": "threat-intelligence-s3-test-bucket",
                                "object_key": "bd",
                                "region": "us-west-2",
                                "role_arn": "arn:aws:iam::540654354201:role/threat_intel_s3_test_role"
                            }
                        },
                        "created_at": 1719449576373,
                        "enabled_time": 1719449576373,
                        "last_update_time": 1719449577824,
                        "schedule": {
                            "interval": {
                                "start_time": 1717097122,
                                "period": 1,
                                "unit": "Days"
                            }
                        },
                        "state": "AVAILABLE",
                        "refresh_type": "FULL",
                        "last_refreshed_time": 1719449576533,
                        "last_refreshed_user": null,
                        "enabled": true,
                        "ioc_types": [
                            "ip",
                            "hash"
                        ]
                    }
                }
            }
        ]
    }
}

위협 인텔리전스 소스 삭제 API

위협 인텔리전스 소스를 삭제해요.

엔드포인트

DELETE /_plugins/_security_analytics/threat_intel/sources/{source-id}

요청 예제

DELETE /_plugins/_security_analytics/threat_intel/sources/2c0u7JAB9IJUg27gcjUp

{% include copy-curl.html %}

응답 예제

{
  "_id": "2c0u7JAB9IJUg27gcjUp"
}

소스 새로 고침

위협 인텔리전스 소스에서 IOC를 다운로드해요. S3_CUSTOM 타입과 URL_DOWNLOAD 타입 소스를 지원해요. IOC_UPLOAD 소스는 IOC를 생성 요청에서 직접 제공하기 때문에 새로 고침이 지원되지 않아요.

엔드포인트

POST /_plugins/_security_analytics/threat_intel/sources/{source-id}/_refresh

요청 예제

POST /_plugins/_security_analytics/threat_intel/sources/IJAXz4QBrmVplM4JYxx_/_refresh

{% include copy-curl.html %}

응답 예제

{
 "acknowledged": true
}

더 알아보기 (Learn more)

함께 읽는 실무 이야기

우리 조직에도 적용하고 싶다면, AI 시스템 구축 서비스를 살펴보세요.