TISDK 接口说明

1.概述

TISDK为各产品提供访问威胁情报云端平台的内嵌接口，能够缓存IOC请求和威胁情报，避免重复请求。SDK以异步方式工作，当威胁情报更新时，通过回调接口传递结果。

2.文件说明

文件名	描述
\64\libpretisdk.so	64 位 Linux 系统动态加载 so 文件（详见 7.进程 Fork 支持）
\64\libtisdk.so	64 位 Linux 系统 so 文件
\64\tisdk.dll	64 位 Win 系统 dll 文件
\64\tisdk.lib	64 位 Win 系统 lib 文件
\32\libpretisdk.so	32 位 Linux 系统动态加载 so 文件（详见 7.进程 Fork 支持）
\32\libtisdk.so	32 位 Linux 系统 so 文件
\32\tisdk.dll	32 位 Win 系统 dll 文件
\32\tisdk.lib	32 位 Win 系统 lib 文件
\test\linux*	linux 系统测试程序和代码（64 位）
\test\win*	win 系统测试程序和代码（64 位）
domain_ioc.zip	测试用的域名 IOC
filehash.list.zip	测试用的文件 IOC（文件 hash）
tisdk_c.h	C 接口头文件
tisdkcfg.json	测试用的配置项

3.C接口

3.1. 初始化 SDK

int ti_init(TI_CALLBACK callback, int truncate);

使用其他接口前调用 ti_init。

callback：传入回调函数指针。当 IOC 更新时，SDK 调用回调函数。

truncate：非 0 值时，清除所有本地缓存的 IOC 记录。

返回值：返回 0 表示成功，<0 表示失败。

itypedef void(*TI_CALLBACK)(const char *json, const char *ctx);

回调函数原型。用于接收 IOC 更新信息。

json：云端返回的威胁情报，JSON 格式。

ctx：查询 IOC 和上传文件操作传入的上下文。

3.2. 身份认证

int ti_login(const char *user, const char *passwd, int rememberMe,
const void *customKey, size_t key_size,
const void *customExtInfo, size_t info_size);

查询 IOC 和上传文件之前，需进行身份认证。

user, passwd：用户名，密码。云端提供。

rememberMe：认证信息保持时间，>0 表示长期有效，具体时间取决于云端。每次使用时 SDK 都需要进行认证。

customKey, key_size：产品相关的 Key 和大小（字节数）。此参数是必须的参数。

customExtInfo, info_size：自定义扩展信息和大小（字节数）。可用于区分不同主机生成的情报。

3.3. 查询 IOC

int ti_query(const char *iocs, const char *ctx);

向云端查询 IOC 信息。如果缓存中存在该情报，则不再请求云端，并尽快通过 Callback 返回信息。

iocs：一个或多个IOC，以逗号分隔。IOC 数量不能超过云端单次查询的限制，目前为1000个。合并查询比每次查询一个效率更高。

ctx：附加的操作上下文。SDK将复制 ctx，并在Callback时传入。注意，如果查询过程出现错误，Callback不会发生，ctx将被丢弃。

3.4. 上传文件

int ti_upload(const char *file_path, int analyze, const char *ctx);

将文件上传到云端等待分析。如果文件 hash 对应的分析结果已经存在，则不再上传云端，并尽快通过 Callback 返回信息。

file_path：文件全路径。

analyze：0 基本分析, 1 深度分析。

ctx：附加的操作上下文。SDK复制 ctx，并在 Callback 时传入。注意，如果上传过程出现错误，Callback不会发生，ctx将被丢弃。

3.5. 获得历史数据页面 URL

int ti_get_url(char *url, size_t *url_size);

登陆操作之后，可通过该接口得到一个 URL，页面展示认证用户相关的历史数据。 调用者可将页面内嵌入产品中。

url：url 缓冲区指针，返回页面的 url。

url_size：输入 url 缓冲区大小，返回 url 实际大小（字节数），不含字符串结尾\0 字 符 。 如果缓存长度不足 ，

返回需要的长度，同时接口返回错误值 TI_ERR_BUF_SIZE。

3.6. 退出 SDK

void ti_term();

停用前清理 SDK。由于操作都是异步进行，如果在查询 IOC 和上传文件操作之后立刻调用本接口，

可能导致之前临近的操作被放弃。

4.Java 接口

/**
* 初始化 SDK
* @param caller 回调对象
* @param truncate 是否清除本地查询记录缓存
* @param configFilePath 配置文件路径
* @return
* @throws ParameterException
*/
public static Result tiInit(ITiCallBacker caller, Integer truncate, String configFilePath) throws
ParameterException;
/**
* 登录平台
* @param user 登录信息
* @return
* @throws ParameterException
*/
public static Result tiLogin(LoginUser user) throws ParameterException;
/**
* 查询 ioc
* @param ioc 批量 ioc
* @param ctx 上下文，对应于回调对象中回调函数的上下文
* @return
* @throws ParameterException
*/
public static Result tiQuery(String ioc, String ctx) throws ParameterException;
/**
* 上传文件
* @param filePath 文件路径
* @param analyze 分析类型 0/1
* @param ctx 上下文
* @return* @throws ParameterException
*/
public static Result tiUpload(String filePath, Integer analyze, String ctx) throws ParameterException;
/**
* 清除 SDK
*/
public static void tiTerm();
/**
* 获取内嵌页面的地址（可内嵌入产品)
* @return
*/
public static String tiGetUrl();

5.多线程支持

SDK 的接口支持多线程调用。

6.多进程支持

SDK 被多个进程同时使用时，第一个进程内的 SDK 将开启基于 socket 的 RPC 服务，其他进程 SDK 作为 RPC 客户端。所有操作通过 RPC 排队到服务端，由服务端统一处理。

RPC 服务进程称为主进程。有几点需要注意的地方：

（1）只有主进程才会进行回调，即使查询请求发生在另一个进程也是如此。

（2）当主进程退出后，剩下的进程会“竞争”成为主进程。只有一个进程能最终“竞争”成功。

（3）如果调用 ti_init 时传递的 callback 指针为空值，则该进程不会成为主进程。此特性可用于控制哪个进程允许成为主进程。

7.进程 Fork 支持

在 Linux 系统上，如果使用 SDK 的进程是 Fork 生成的，必须使用 dlopen 动态加载 libtisdk.so， 不能静态链接。一旦动态加载 SDK 后，不能再 Fork 子进程。

为了方便使用，由 libpretisdk.so 提供一组转发接口，接口内部自动加载 libtisdk.so。有进程 Fork 需要的产品可使用 libpretisdk.so 代替 libtisdk.so。

目前转发接口只有 C 接口，没有 Java 接口。

8.工作模式

（1）缓存模式：默认配置下，SDK 工作在缓存模式。该模式下查询 IOC 和上传文件操作首先缓存到自带的数据库中，定时向云端发出请求，订阅 IOC 更新。该模式适合长期运行的产品。

（2）直接模式：该模式下 SDK 不缓存操作到数据库，直接向云端发起查询（但操作依然是异步的）。SDK 不订阅 IOC 更新，不会调用 Callback。要获取情报可通过 ti_get_url 返回的页面。该模式适合临时运行的工具箱类产品。详见配置项 WorkingMode 。

（3）离线模式：待开发。

9.配置项

SDK 初始化时从当前目录下的 tisdkcfg.json 文件读取配置。除了工作模式，其他配置项基本上无需特别设置，采用默认配置即可。可配置的选项包括如下表。

字段名	默认值	含义
StorageDir	"./Storage"	保存数据库的目录路径
BackendURI	"http://api.web saas.cn/ti"	云端 Web 接口的 URI
WorkingMode	"Cache”	工作模式。取值为”Direct”时，SDK 工作在直接模式，否则工作在缓存模式
RunGCAndSyncInterval	60	对SDK和数据库执行垃圾回收和同步的时间间隔（单位秒）
DebugOutput	false	是否输出调试信息
ConsoleOutput	false	是否通过控制台输出调试信息
LogFileOutput	false	是否通过日志文件输出调试信息（日志保存在 StorageDir 中）
RPCServerPort	20402	RPC 服务端口号
RPCConnLimit	100	RPC 客户端限制数量，等于限制了同时使用 SDK 的进程数量
RPCServerKeepAliveInterv al	10000	RPC 服务保持存活的轮询时间（单位毫秒），用于定时创建 RPC 服务
RPCClientDialTimeout	1000	RPC 客户端连接超时时间（单位毫秒）
RPCClientDialInterval	3000	RPC 客户端连接重试间隔时间（单位毫秒）
LoadIocQueryInterval	3000	从数据库中获得等待推送 IOC 的重试间隔时间（单位毫秒），应根据设备产生 IOC 的频率和数量确定时间
LoadIocQueryLimit	800	每次从数据库获得 IOC 的最大数量，不能大于云端一次查询能接受的 IOC 数量（目前是1000 个）
BatchQueryIocInterval	0	向云端推送 IOC 的两次请求间的最小时间间隔（单位毫秒），如果值为 0 则不等待
LoadUploadFileInterval	3000	从数据库中获得等待上传文件的重试间隔时间（单位毫秒），应根据设备上传文件的频率和数量确定时间
UploadFileInterval	0	上传文件请求之间的最小时间间隔（单位毫秒），如果值为 0 则不等待
UpdateIocInterval	1000	向云端订阅 IOC 更新的间隔时间（单位毫秒）
UpdateIocLimit	100	每次拉取 IOC 更新的最大条目
QueryIocChanSize	2000	用于排队 IOC 查询的管道容量，如果查询量非常大，应增大该值
UploadFileChanSize	500	用于排队上传文件的管道容量
QueryIocChanTimeout	2000	当 IOC 查询管道装满，指定超时时间（单位毫秒），以尽快返回错误给调用者
UploadFileChanTimeout	2000	当上传文件管道装满，指定超时时间（单位毫秒），以尽快返回错误给调用者
IgnoreEmptyFile	true	上传文件是否忽略空文件
UploadFileSizeLimit	1010241024	限制上传文件的大小（单位字节），太大的文件上传和计算 hash 太慢，会导致拒绝服务
QueryIocTTL	60	数据库中等待推送的 IOC 记录的生存时间 （单位分钟）
UploadFileTTL	60	数据库中等待上传文件记录的生存时间（单位分钟）
QueryIocCtxTTL	60*12	数据库中等待更新 IOC 记录的生存时间（单位分钟）
UploadFileCtxTTL	60*72	数据库中等待文件分析结果记录的生存时间（单位分钟）
BackendLoginTimeout	5000	向云端请求登陆的超时时间（单位毫秒）
BackendPushIocTimeout	5000	向云端推送 IOC 的超时时间（单位毫秒）
BackendUploadFileTimeout	5000	向云端上传文件的超时时间（单位毫秒）
BackendUpdateIocTimeout	5000	向云端订阅 IOC 更新的超时时间（单位毫秒）
TestConfig		测试专用配置
UserName	无默认值	如果指定，则覆盖 ti_login 的同名参数值
Password	无默认值	如果指定，则覆盖 ti_login 的同名参数值
RememberMe	无默认值	如果指定，则覆盖 ti_login 的同名参数值
CustomKey	无默认值	如果指定，则覆盖 ti_login 的同名参数值
CustomExtInfo	无默认值	如果指定，则覆盖 ti_login 的同名参数值
DeviceID	无默认值	覆盖 SDK 自动生成的设备 ID
Token	无默认值	覆盖云端返回的 Token
BackendURI	无默认值	覆盖配置的和默认的 BackendURI 值

10.测试程序

以 linux 为例，test/linux 目录下，执行命令： ./titest 10 从 domain_ioc.list 读取10个 IOC 提交查询。等一段时间，输出查询结果。由于云端对同一个设备的查询同样 IOC，只返回一次结果。

7 天内重复查询不会再次返回结果。因此测试时，可以修改配置文件 tisdkcfg.json，将 TestConfig 里的 DeviceID 改成其他任意值。以便云端认为这是不同的设备。