{"id":26164735,"url":"https://github.com/optum/kong-plugin-icap","last_synced_at":"2025-07-07T14:09:26.793Z","repository":{"id":94608643,"uuid":"386644599","full_name":"Optum/kong-plugin-icap","owner":"Optum","description":"Kong plugin to pull file attachment data in a request payload and conduct anti-virus scanning leveraging the ICAP protocol","archived":false,"fork":false,"pushed_at":"2022-03-28T20:40:28.000Z","size":23,"stargazers_count":0,"open_issues_count":1,"forks_count":2,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-11T15:51:12.412Z","etag":null,"topics":["api-gateway","kong","optum"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Optum.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-07-16T13:21:13.000Z","updated_at":"2021-11-22T22:10:46.000Z","dependencies_parsed_at":"2023-04-24T14:02:01.303Z","dependency_job_id":null,"html_url":"https://github.com/Optum/kong-plugin-icap","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Optum/kong-plugin-icap","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Optum%2Fkong-plugin-icap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Optum%2Fkong-plugin-icap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Optum%2Fkong-plugin-icap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Optum%2Fkong-plugin-icap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Optum","download_url":"https://codeload.github.com/Optum/kong-plugin-icap/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Optum%2Fkong-plugin-icap/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264089653,"owners_count":23555782,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-gateway","kong","optum"],"created_at":"2025-03-11T15:40:02.722Z","updated_at":"2025-07-07T14:09:26.787Z","avatar_url":"https://github.com/Optum.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"# kong-plugin-icap\nVirus scanner plugin for Kong APIGateway leveraging ICAP protocol\n\n## Configuration \nThe plugin can be added to a route with the following request to the Kong Admin endpoint. \n```\n$ curl -X POST http://kong:8001/apis/{route}/plugins \\\n    --data \"name=kong-plugin-icap\" \\\n    --data \"config.icap_host=host.ip.of.icap.server\" \\\n    --data \"config.icap_port={port number of icap server} \\\n    --data \"config.icap_service=icap://{icap host ip}:{icap port}/{name of icap service}\" \\\n    --data \"config.timeout=TIMEOUT_DURATION\" \\\n    --data \"config.keepalive=KEEPALIVE_DURATION\" \\\n    --data \"config.content_to_scan=text/plain, application/pdf, etc.\" \\\n    --data \"config.tls={true or false}\" \\\n    --data \"config.tls_sni={server name indicator}\n```\n\n| Form Parameter | required | default | description |\n| -------------- | -------- | ------- | ----------- |\n| `name`         | yes      |         | plugin name `kong-plugin-icap`|\n| `config.icap_host`    | yes      |         | the host ip that the icap server is running on |\n| `config.icap_port`    | yes      |         | the port number that the icap server is running on |\n| `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 |\n| `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. |\n| `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. |\n| `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 |\n| `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. |\n| `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. |\n\n\n## Supported Kong Releases\nKong \u003e= 1.0\n\n## Installation\nRecommended: \n```\n$ luarocks install kong-plugin-auth\n```\nNOTE, not yet pushed to luarocks - update this doc when completed\n\nOther: \n```\n$ git clone https://github.com/Optum/kong-plugin-icap.git /path/to/kong/plugins/kong-plugin-icap\n$ cd /path/to/kong/plugins/kong-plugin-icap\n$ luarocks make *.rockspec\n```\n## DB less mode \nThis plugin can also be configured with a declarative config yaml file. See the following example. \n\n### kong.yml\n```\n_format_version: \"1.1\"\n\nservices:\n- name: example-service\n  url: {some_service_url.com}\n  tags:\n  - example\n  routes:\n  - name: vscanning\n    paths: \n    - /vs\n\nplugins:\n- name: kong-plugin-icap\n  config:\n    icap_host: {\"icap.ip.address\"}\n    icap_port: {port#}\n    icap_service: \"icap://{icap_host}:{icap_port}/{name_of_icap_service}\"\n\n    timeout: 10000\n    keepalive: 120000\n\n    content_to_scan: [\"multipart/form-data\", \n    \"application/x-www-form-urlencoded\", \n    \"application/pdf\", \n    \"application/zip\", \n    \"text/plain\", \n    \"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet\", \n    \"application/vnd.openxmlformats-officedocument.wordprocessingml.document\",\n    \"application/vnd.ms-excel\",\n    \"application/msword\"]  \n\n    tls: false \n    tls_sni: {\"tls_server_name_indicator\"}\n```\nAlso needed is a `kong.conf` file \n\n### kong.conf\n```\nproxy_listen=0.0.0.0:8080\nproxy_error_log=/dev/stderr\nadmin_error_log=/dev/stderr\ndatabase=off\ndeclarative_config=/{location/of/kong.yml}\n\nplugins=bundled,kong-plugin-icap\n# this optional config field defines the max payload size\nnginx_http_client_body_buffer_size = 50M \n```\n\nNavigate to the running instance of kong and run the following:\n\n```\ncd {location of the directory with kong.conf file within kong}\nkong start -c kong.conf\n```\n\nFor further details on declarative configs in Kong reference [this](https://docs.konghq.com/gateway-oss/2.3.x/db-less-and-declarative-config/)\n\n## Maintainers \n\n- [AntonyGor](https://github.com/AntonyGor)\n- [jeremyjpj0916](https://github.com/jeremyjpj0916)\n\nFeel free to open issues, or refer to the [Contribution Gidelines](./CONTRIBUTING.md) if you have any questions. \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foptum%2Fkong-plugin-icap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foptum%2Fkong-plugin-icap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foptum%2Fkong-plugin-icap/lists"}