This topic describes the syntax and parameters of value-added content functions. This topic also provides examples on how to use the functions.

Functions

Category Function Description
Threat intelligence e_threat_intelligence Obtains the threat intelligence for an IP address or a domain name that is specified by a log field and assigns the threat intelligence as a value to a specified field.
Risk identification e_saf Obtains the risk identification information about an IP address that is specified by a log field and assigns the risk identification information as a value to a specified field.

e_threat_intelligence

The e_threat_intelligence function obtains the threat intelligence for an IP address or a domain name that is specified by a log field and assigns the threat intelligence as a value to a specified field.
  • If no threat intelligence is found for the specified IP address or domain name, no data is assigned as a value to the specified field, and your data transformation job is not affected.
  • Alibaba Cloud Threat Intelligence provides the threat intelligence of the last 30 days and updates the threat intelligence once a day. If you want to obtain detailed threat intelligence, you can activate Threat Intelligence.
Note The e_threat_intelligence function is in public preview. You can call this function free of charge when you use the data transformation feature. The number of times that you can call the function is unlimited.
The e_threat_intelligence function is available in the following regions.
Region
China (Hangzhou) China (Chengdu)
China East 1 Finance China (Hong Kong)
China (Shanghai) Japan (Tokyo)
China East 2 Finance South Korea (Seoul)
China (Qingdao) Singapore (Singapore)
China (Beijing) Australia (Sydney)
China North 2 Finance Malaysia (Kuala Lumpur)
China North 2 Ali Gov 1 Indonesia (Jakarta)
China (Zhangjiakou) Philippines (Manila)
China (Hohhot) UAE (Dubai)
China (Ulanqab) US (Silicon Valley)
China (Shenzhen) Germany (Frankfurt)
China South 1 Finance US (Virginia)
China (Heyuan) India (Mumbai)
China (Guangzhou) UK (London)
  • Syntax

    e_threat_intelligence(category, field, output_field=None, mode="overwrite")    
  • Parameters

    Parameter Type Required Description
    category String Yes The type of the threat intelligence. Valid values:
    • ip: obtains the threat intelligence for an IP address.
    • domain: obtains the threat intelligence for a domain name.
    field String Yes The name of the log field that is used to obtain the threat intelligence.
    output_field String No The name of the field to which the threat intelligence is assigned as a value. If you do not configure this parameter, the threat intelligence is assigned as a value to the __threat_intelligence__:field field by default.
    mode String No The overwrite mode of fields. Default value: overwrite. For more information, see Field extraction check and overwrite modes.
  • Response

    The threat intelligence is returned in the JSON format to the field specified by the output_field parameter. The following tables describe the parameters in the threat intelligence.
    • Threat intelligence for an IP address
      Parameter Description
      confidence The confidence level of the threat intelligence. The value is an integer within the range of [0,100]. A larger value indicates a higher confidence level.
      severity The threat level of the threat intelligence.
      • 0: no risk
      • 1: low risk
      • 2: medium risk
      • 3: high risk
      • 4: critical risk
      family The malware family. An empty string is returned.
      ioc_type The type of the threat intelligence. The value is fixed as ipv4. Only IPv4 IP addresses are supported.
      ioc_raw The IP address for which the threat intelligence is obtained.
      intel_type The type of the risk tag. Multiple risk tags are separated with commas (,).
      • web_attack: an IP address from which a network attack is initiated.
      • tor: an IP address of a Top of Rack (TOR) node.
      • mining: an IP address of a mining program.
      • c2: an IP address of a command and control (C2) server.
      • malicious: an IP address of a malicious download source.
      • exploit: an IP address from which an exploit attack is initiated.
      • webshell: an IP address from which a webshell attack is initiated.
      • scan: an IP address from which a network service scan is initiated.
      country The country to which the IP address belongs.
      province The province to which the IP address belongs.
      city The city to which the IP address belongs.
      isp The telecommunications carrier of the network to which the IP address belongs.
    • Threat intelligence for a domain name
      Parameter Description
      confidence The confidence level of the threat intelligence. The value is an integer within the range of [0,100]. A larger value indicates a higher confidence level.
      severity The threat level of the threat intelligence.
      • 0: no risk
      • 1: low risk
      • 2: medium risk
      • 3: high risk
      • 4: critical risk
      family The malware family. An empty string is returned.
      ioc_type The type of the threat intelligence. The value is fixed as domain.
      ioc_raw The domain name for which the threat intelligence is obtained.
      intel_type The type of the risk tag. Multiple risk tags are separated with commas (,). For more information, see Risk tags of domain names.
      root_domain The root domain name to which the domain name belongs.
  • Examples

    • Example 1: Obtain the threat intelligence for an IP address and assign the threat intelligence as a value to a specified field.
      • Raw log
        remote_addr: 203.0.113.1
        method: GET
      • Transformation rule
        Obtain the threat intelligence for the IP address specified by the remote_addr field and assign the threat intelligence as a value to the threat_info field.
        e_threat_intelligence("ip", "remote_addr", output_field="threat_info")
      • Result
        threat_info:{
            "confidence": 100,
            "severity": 4,
            "family": "",
            "ioc_raw": "203.0.113.1",
            "ioc_type": "ipv4",
            "intel_type": "web",
            "country": "China",
            "province": "Zhejiang",
            "city": "Hangzhou",
            "isp": "China Telecom"
            }
        method:GET
        remote_addr:203.0.113.1
    • Example 2: Obtain the threat intelligence for an IP address and assign the threat intelligence as a value to the default field.
      • Raw log
        remote_addr: 203.0.113.1
        method: GET
      • Transformation rule
        Obtain the threat intelligence for the IP address specified by the remote_addr field and assign the threat intelligence as a value to the default field.
        e_threat_intelligence("ip", "remote_addr")
      • Result
        __threat_intelligence__:remote_addr:{
            "confidence": 100,
            "severity": 4,
            "family": "",
            "ioc_raw": "203.0.113.1",
            "ioc_type": "ipv4",
            "intel_type": "web",
            "country": "China",
            "province": "Zhejiang",
            "city": "Hangzhou",
            "isp": "China Telecom"
            }
        method:GET
        remote_addr:203.0.113.1
    • Example 3: Obtain the threat intelligence for a domain name and assign the threat intelligence as a value to a specified field.
      • Raw log
        domain_name: www.02a470ee85e5c43f27b9c42a3c46a8bb.info
      • Transformation rule
        Obtain the threat intelligence for the domain name specified by the domain_name field and assign the threat intelligence as a value to the _ti_ field.
        e_threat_intelligence("domain", "domain_name", output_field="_ti_")
      • Result
        domain_name: www.02a470ee85e5c43f27b9c42a3c46a8bb.info
        _ti_: {
          "confidence": 91,
          "severity": 3,
          "family": "",
          "ioc_raw": "www.02a470ee85e5c43f27b9c42a3c46a8bb.info",
          "ioc_type": "domain",
          "root_domain": "02a470ee85e5c43f27b9c42a3c46a8bb.info",
          "intel_type": "sinkhole;rat_trojan;js_miner"
        }

e_saf

The e_saf function obtains the risk identification information about an IP address that is specified by a log field and assigns the risk identification information as a value to a specified field.

  • If no risk information is obtained for the specified IP address, no data is assigned as a value to the specified field, and your data transformation job is not affected.
  • Alibaba Cloud Fraud Detection provides the risk identification information.
Note The e_saf function is in public preview. You can call this function free of charge when you use the data transformation feature. The number of times that you can call the function is unlimited.
The e_saf function is available in the following regions.
Region
China (Chengdu) China (Beijing)
China (Shanghai) Singapore (Singapore)
  • Syntax

    e_saf(category, field, output_field=None, mode="overwrite") 
  • Parameters

    Parameter Type Required Description
    category String Yes The type of the risk identification information. Set the value to ip, which specifies that the risk identification information about an IP address is obtained.
    field String Yes The name of the log field that is used to obtain the risk identification information.
    output_field String No The name of the field to which the risk identification information is assigned as a value. If you do not configure this parameter, the risk identification information is assigned as a value to the __saf__:field field.
    mode String No The overwrite mode of fields. Default value: overwrite. For more information, see Field extraction check and overwrite modes.
  • Response

    The risk identification information is returned in the JSON format to the field specified by the output_field parameter. The following table describes the parameters in the risk identification information.
    Parameter Description
    isIdc Indicates whether the IP address belongs to a data center.
    • 0: no
    • 1: yes
    isProxy Indicates whether the IP address is a proxy IP address.
    • 0: no
    • 1: yes
    isNat Indicates whether the IP address is a NAT IP address.
    • 0: no
    • 1: yes
    isBase Indicates whether the IP address is a base station IP address.
    • 0: no
    • 1: yes
    score The confidence level of the risk identification information. The value is within the range of [0,1]. A larger value indicates a higher risk.
    • 0: low risk
    • (0,0.35]: medium risk
    • (0.35,0.5]: medium and high risk
    • (0.5,1]: high risk
  • Examples

    • Example 1: Obtain the risk identification information about an IP address and assign the risk identification information as a value to the default field.
      • Raw log
        remote_addr: 203.0.113.1
      • Transformation rule
        Obtain the risk identification information about the IP address specified by the remote_addr field and assign the risk identification information as a value to the default field.
        e_saf("ip", "remote_addr")
      • Result
        __saf__:remote_addr: {
        "score": 0.0,
        "isIdc": 0,
        "isNat": 0,
        "isBase": 0,
        "isProxy": 0
        }
        remote_addr:203.0.113.1
    • Example 2: Obtain the risk identification information about an IP address and assign the risk identification information as a value to a specified field.
      • Raw log
        remote_addr: 203.0.113.1
      • Transformation rule
        Obtain the risk identification information about the IP address specified by the remote_addr field and assign the risk identification information as a value to the _saf_ field.
        e_saf("ip", "remote_addr",output_field="_saf_")
      • Result
        _saf_:  {
        "score": 0.0,
        "isIdc": 0,
        "isNat": 0,
        "isBase": 0,
        "isProxy": 0
        }
        remote_addr:203.0.113.1

Appendix

Table 1. Risk tags of domain names
Risk tag Description Risk tag Description
malware Malware botnet Botnet
spy_trojan Trojan-spy trojan Trojan
worm Worm bank_trojan Banker trojan
ransomware Ransomware adware Adware
backdoor_trojan Backdoor trojan exploit Exploit
hacktool Hacking tool malicious_doc Malicious document
infected_virus Infectious virus bootkit_trojan Bootkit trojan
trojan_dropper Trojan dropper script_trojan Trojan script
riskware Riskware virus Virus
apt APT trojan_downloader Trojan downloader
rat_trojan Remote access trojan (RAT) rat RAT
hijack Hijack ddos_trojan DDoS trojan
macro_virus Macro virus spam_email Spam
porn Pornographic website js_miner JavaScript mining
rootkit_trojan Rootkit trojan compromised_host Compromised host
private_server Private server gamble Gambling website
c2 C2 server dnslog_attack DNSLog attack
miner Mining infostealer Information stealer
malicious_group Malicious group malicious Malicious website
sinkhole Sinkhole miner_pool Mining pool
dga DGA None None