apicat

基于OpenAPI的Nginx和云上HTTP服务日志分析器，通过调取OpenAPI定义文档，对HTTP请求中的异常请求进行分析，以达到预警分析等目的。

原理

OpenAPI是一种用于定义API结构的规范，在Java里我们可以使用swagger进行自动生成。其他语言也可以（Golang等）。通过这种对开发人员零成本的工具，我们可以高效的获取开放API服务的业务结构、合理输入及输出等描述信息。

结合这种描述信息以及实际发生的访问日志，我们就可以有效的对恶意访问进行筛选，比如常见的各式扫描访问（通过常见的管理页面、登录页面等扫描访问服务，达到获取服务漏洞的目的）。

安装方式

安装到本地

go install gitee.com/bjf-fhe/apicat

使用docker

使用docker运行本程序

指定参数

系统中所有的运行参数都可以通过配置文件或者环境变量的形式进行配置，优先级别为

命令行参数 > 环境变量 > 配置文件

使用配置文件指定参数

所有运行参数可以通过挂载apicat.yaml文件进行配置，配置文件格式为yaml格式。例如运行参数中以--definition的形式传输的参数可以在配置文件中使用

definition: xxxx

的形式进行配置。

使用环境变量指定参数

除了使用配置文件之外，所有运行参数可以通过环境变量的形式进行配置，所有的环境变量前缀都为APICAT_，还以definition为例，可以设置环境变量APICAT_DEFINITION进行配置，建议大写，实际程序探测时，大小写无关。

中间有-的参数，当用环境变量进行设置时，使用_代替-，例如参数--aliyun-accesskey-id，当使用环境变量进行设置时，环境变量对应的是APICAT_ALIYUN_ACCESSKEY_ID

获得docker image

docker push baijiafan/apicat

运行docker

docker命令模式

docker run baijiafan/apicat:latest watch 运行监控程序 docker run baijiafan/apicat:latest report 运行报告生成程序

所需各项运行参数可选择命令行输入，或采用挂载配置文件、指定环境变量等形式进行输入

docker-compose命令模式

example/aliyun下的docker-compose.yaml文件是运行apicat的样例docker-compose配置文件，默认运行watch命令，可修改command修改，各项参数和环境变量，可通过文件修改。完成后通过docker-compose up运行即可，运行监控命令可使用docker-compose up -d后台运行。

初始配置

初始运行会抛出异常：

SDKError: StatusCode: 404 Code: InvalidAccessKeyId.NotFound Message: code: 404, Specified access key is not found. request id: 1C60495D-AF84-5A23-8628-145E6993A4C0 Data: {"Code":"InvalidAccessKeyId.NotFound","HostId":"slb.aliyuncs.com","Message":"Specified access key is not found.","Recommend":"https://next.api.aliyun.com/troubleshoot?q=InvalidAccessKeyId.NotFound\u0026product=Slb","RequestId":"1C60495D-AF84-5A23-8628-145E6993A4C0","statusCode":404}

初始配置可以拷贝example/aliyun下的apicat.yaml文件，修改以下参数：

AliyunAccesskeyId: xxxx

AliyunAccesskeySecret: xxxx

AliyunRegionId: cn-xxx

AliyunDest: acl-xxx

并通过挂载覆盖默认配置。

或者通过修改docker-compose.yaml文件中的环境变量修改，或通过docker命令的环境变量参数修改

    environment:
      - APICAT_DEFINITION=./openapi.yaml
      - APICAT_ALIYUN_ACCESSKEY_ID=xxxx
      - APICAT_ALIYUN_ACCESSKEY_SECRET=xxxx
      - APICAT_ALIYUN_REGION_ID=xxxx

默认参数

docker image中默认配置文件中配置为从阿里云负载均衡日志读取日志，并写入拦截规则到拦截列表。修改账户信息运行后，会扫描日志中的错误访问，并写入拦截规则。

如果想测试一下读取效果，可以通过配置文件配置dest: echo来将写入目的改为本地回显。该模式会通过docker日志显示判定为非法的条目信息。

使用方式

使用go命令进行安装之后，运行apicat+子命令即可。子命令接收本文档的通用运行参数和一些特有参数的配置。特有参数配置参考子命令配置说明

子命令：report

apicat report

生成访问报告，运行命令后，会生成report.html，默认会调用系统命令进行打开

子命令：watch

apicat watch

实时监听访问日志，运行命令后，会监听日志文件变化，并根据规则实现对访问者ip的放行/阻止

子命令参数说明看这里

注意：参数可能随版本变化扩展，可能存在文档更新不及时的情况，最新情况请运行apicat --help或者apicat 子命令 --help获得。

通用运行参数

Flags:
      --cache-db string            缓存数据库文件路径 (default "./apicat.db")
  -c, --config string              配置文件路径 (default "./apicat.yaml")
  -d, --definition string          OpenAPI definition (default "./openapi.yaml")
  -h, --help                       help for apicat
      --ip-hash-length int         IP地址哈希长度，用于设置缓存IP地址的哈希值长度，长度越大，精度越高，但内存占用越大 (default 32)
      --log-level int              日志级别，默认为3（Warning），可设置0（Panic）-1（Fatal）-2（Error）-4（Info）-5（Debug）-6（Trace） (default 3)
  -p, --password string            百家饭平台用户密码
  -s, --server string              选择使用那个服务器，可以输入'/'或者数字编号，数字编号对应OpenAPI服务器配置的编号，默 认为0，也就是从OpenAPI文档中选择第一个 (default "0")
      --server_variables strings   如果服务器地址有参数存在，可以通过该参数传入变量，输入形式为名称:值
      --source string              日志来源模式，支持nginx/aliyun/aws (default "nginx")
      --static_types strings       静态文件的后缀，列表中的文件类型会被认为是静态文件 (default [.js,.png,.jpg,.jpeg,.js,.css,.html,svg])
      --time-formate string        默认时间格式，Nginx模式用于解析time_local,对time_iso8601无效 (default "02/Jan/2006:15:04:05 -0700")
  -u, --username string            百家饭平台用户名/手机号/邮箱
      --wellknown string           一些常见的未定义url

Use "apicat [command] --help" for more information about a command.

其中，-d可以输入：

• 数字，指百家饭平台的source id，输入数字的时候，需要提供-u参数指定平台用户名
• url，网络上的openapi定义url，如果是本地的swagger服务器，可以参考这个指引获得定义json
• 本地文件路径

-c是指定的nginx配置文件路径，主要要从该文件中获取log_format，以便匹配日志条目，如果不指定，会使用默认配置。默认配置为： log_format main '$remote_addr [$time_local] "$request"' 如果不方便指定原始nginx配置，可以自行编辑包含以上内容的文本作为输入，仅包含该行即可

-f是指定的nginx配置中log_format的名称，log_format在nginx配置中，紧跟log_format是log_format的名称，通常为main，此时不需要单独指定该配置，如果配置中有修改，需要通过该参数指定。

本地cache说明

为进行深度URL访问有效性判定，APIcat会将历史日志分析中的部分信息进行本地化持久存储，持久存储的文件名由参数--cache-db指定。默认为"./apicat.db"

IP Hash长度

--ip-hash-length 参数是配合cache-db参数进行深度URL访问有效性判定的辅助参数，默认情况可以不用更改，如果执行APIcat的环境内存或硬盘存储容量不足时，可以调小该参数值，该参数控制程序内部对访问IP取Hash值的长度，当取值变小时，可能出现多个IP被认为是同一个IP的情况，因此会影响判定精度。

指定日志路径

日志路径在运行参数的最后一位提供即可。

来源日志类型

• Nginx 日志
• Aliyun 导出CSV日志（从Aliyun日志库导出的csv类型的日志文件，不需要解压，直接将gz文件作为传入参数即可，导出日志时，请选择CSV类型，压缩方式选择默认的gz格式 ）
• Aliyun 日志存储在线读取（支持从阿里云负载均衡配置的日志存储点直接获取在线日志条目）
• AWS AWS ALB负载均衡日志读取（S3来源，需配置日志S3存储）

常见合法Url

除了自定义的Url之外，APIcat提供了一份常见url的OPENAPI文件，用于在监控中排除常见的URL，以免OPENAPI定义的时候覆盖不全，包括

• / 根路径
• /favorite.ico 网站图标
• /robot.txt

文件加载方式

上述文件默认在docker文件中包含，docker中默认启用该文件。

本地安装的可以从仓库中拷贝获得本文件，并通过--wellknown函数指定。

修改并重新加载

可以编辑该文件加入新的路径，并通过--wellknown指定该文件。

Docker可以通过挂载形式加入。

最新状态

正在准备第一个初步功能版本，暂定为0.1.0，docker线上最新版本为0.1.0_alpha，尽请期待

其他帮助

如果想了解更多关于openapi的功能，请访问我们的网站，或在官方论坛留言

修改本开源软件

本软件的UI部分采用vue编写，需要将其进行编译后生成成为golang template（更新result目录下的template.go中的defaultTemplate变量）。编译步骤如下:

  cd ui && yarn build
  go run ./tool .\ui\dist\index.html