optum / kong-plugin-icap

Kong plugin to pull file attachment data in a request payload and conduct anti-virus scanning leveraging the ICAP protocol

kong-plugin-icap

Virus scanner plugin for Kong APIGateway leveraging ICAP protocol

Configuration

The plugin can be added to a route with the following request to the Kong Admin endpoint.

$ curl -X POST http://kong:8001/apis/{route}/plugins \
    --data "name=kong-plugin-icap" \
    --data "config.icap_host=host.ip.of.icap.server" \
    --data "config.icap_port={port number of icap server} \
    --data "config.icap_service=icap://{icap host ip}:{icap port}/{name of icap service}" \
    --data "config.timeout=TIMEOUT_DURATION" \
    --data "config.keepalive=KEEPALIVE_DURATION" \
    --data "config.content_to_scan=text/plain, application/pdf, etc." \
    --data "config.tls={true or false}" \
    --data "config.tls_sni={server name indicator}

Form Parameter	required	default	description
name	yes		plugin name kong-plugin-icap
config.icap_host	yes		the host ip that the icap server is running on
config.icap_port	yes		the port number that the icap server is running on
config.icap_service	yes		the service name that will conduct virus scanning on the side of icap. Note, the formatting convention shown in the example above is standard for icap services
config.timeout	no	10000	sets the upper timeout limit for making a socket tcp connection to the icap server in milliseconds. By default, this field indicates that requests taking more than 10 seconds will timeout.
config.keepalive	no	120000	sets the upper keepalive limit for creating a new socket connection to the icap server in milliseconds. By default, this field will allow open socket connections to be added to a connection pool and reused for up to two minutes.
config.content_to_scan	yes	"text/plain", "multipart/form-data", "application/x-www-form-urlencoded", "application/pdf", "application/zip", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "application/vnd.ms-excel", "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "application/msword", "application/octet-stream"	whitelist of content-types that will be accepted to scan. If a content-type is detected and not on the whitelist, a 415 Unsupported Media Type status code will be returned back to the client. Note, if a content-type is desired to be scanned in addition to what is whitelisted, all whitelisted content-types will need to be redefined in this field
config.tls	no	false	boolean value indicating whether or not tls is enabled with the icap server. If it is, a TLS handshake will be performed.
congif.tls_sni	no	if the config.tls parameter is enabled, this field must be defined in order to perform the TLS handshake with the icap server.

Supported Kong Releases

Kong >= 1.0

Installation

Recommended:

$ luarocks install kong-plugin-auth

NOTE, not yet pushed to luarocks - update this doc when completed

Other:

$ git clone https://github.com/Optum/kong-plugin-icap.git /path/to/kong/plugins/kong-plugin-icap
$ cd /path/to/kong/plugins/kong-plugin-icap
$ luarocks make *.rockspec

DB less mode

This plugin can also be configured with a declarative config yaml file. See the following example.

kong.yml

_format_version: "1.1"

services:
- name: example-service
  url: {some_service_url.com}
  tags:
  - example
  routes:
  - name: vscanning
    paths: 
    - /vs

plugins:
- name: kong-plugin-icap
  config:
    icap_host: {"icap.ip.address"}
    icap_port: {port#}
    icap_service: "icap://{icap_host}:{icap_port}/{name_of_icap_service}"

    timeout: 10000
    keepalive: 120000

    content_to_scan: ["multipart/form-data", 
    "application/x-www-form-urlencoded", 
    "application/pdf", 
    "application/zip", 
    "text/plain", 
    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", 
    "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
    "application/vnd.ms-excel",
    "application/msword"]  

    tls: false 
    tls_sni: {"tls_server_name_indicator"}

Also needed is a kong.conf file

kong.conf

proxy_listen=0.0.0.0:8080
proxy_error_log=/dev/stderr
admin_error_log=/dev/stderr
database=off
declarative_config=/{location/of/kong.yml}

plugins=bundled,kong-plugin-icap
# this optional config field defines the max payload size
nginx_http_client_body_buffer_size = 50M 

Navigate to the running instance of kong and run the following:

cd {location of the directory with kong.conf file within kong}
kong start -c kong.conf

For further details on declarative configs in Kong reference this

Maintainers

• AntonyGor
• jeremyjpj0916

Feel free to open issues, or refer to the Contribution Gidelines if you have any questions.

kong-plugin-icap's Issues

How to build this project?

Hi,

I am very keen to use this plugin in a db-less Kong setup.

How can I build this plugin to integrate it into a kong installation?

Trying to build it with $ luarocks make *.rockspec results in:

Error: File not found: *.rockspec

So I put a .rockspec file together with this content:

package = "kong-plugin-icap"
version = "1.0-0"
source = {
   url = "git+https://github.com/Optum/kong-plugin-icap.git"
}
description = {
   summary = "Kong plugin designed to scan http payload against an ICAP server.",
   detailed = [[
   Virus scanner plugin for Kong APIGateway leveraging ICAP protocol.
   ]],
   homepage = "https://github.com/Optum/kong-plugin-icap",
   license = "Apache 2.0"
}
dependencies = {}
build = {
   type = "builtin",
   modules = {
      ["kong.plugins.kong-plugin-icap.handler"]  = "handler.lua",
      ["kong.plugins.kong-plugin-icap.schema"]= "schema.lua"
   }
}

But I don't think, that I am on the right way. Something or some "glue code" is missing.

Unfortunately I am completely new to Lua, this is my first contact with this language.

Are you planing to release this plugin on Kong Plugin Hub?

Thanks,
Wahid