{"id":20445879,"url":"https://github.com/rapid7/r7insight_docker","last_synced_at":"2025-04-13T00:44:24.564Z","repository":{"id":32111685,"uuid":"95443633","full_name":"rapid7/r7insight_docker","owner":"rapid7","description":"Docker logging support for InsightOps","archived":false,"fork":false,"pushed_at":"2024-11-06T08:54:22.000Z","size":528,"stargazers_count":7,"open_issues_count":4,"forks_count":7,"subscribers_count":44,"default_branch":"master","last_synced_at":"2024-12-18T06:23:46.717Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rapid7.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"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":"2017-06-26T12:21:45.000Z","updated_at":"2024-11-06T08:54:27.000Z","dependencies_parsed_at":"2024-01-24T17:51:22.013Z","dependency_job_id":"7aeb5621-1f1e-4c46-8497-270832b5ba50","html_url":"https://github.com/rapid7/r7insight_docker","commit_stats":{"total_commits":96,"total_committers":23,"mean_commits":4.173913043478261,"dds":0.71875,"last_synced_commit":"a5decec65e2f222202770577c035517c0f54083a"},"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rapid7%2Fr7insight_docker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rapid7%2Fr7insight_docker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rapid7%2Fr7insight_docker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rapid7%2Fr7insight_docker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rapid7","download_url":"https://codeload.github.com/rapid7/r7insight_docker/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248650419,"owners_count":21139672,"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":[],"created_at":"2024-11-15T10:15:11.026Z","updated_at":"2025-04-13T00:44:24.522Z","avatar_url":"https://github.com/rapid7.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# r7insight_docker\n\n- [r7insight_docker](#r7insight_docker)\n  - [Arguments](#arguments)\n    - [Mandatory arguments](#mandatory-arguments)\n      - [Token](#token)\n      - [Region](#region)\n    - [Optional arguments](#optional-arguments)\n      - [Filtering](#filtering)\n        - [Notes](#notes)\n        - [Filters](#filters)\n  - [Usage as a Container](#usage-as-a-container)\n    - [Docker Arguments](#docker-arguments)\n    - [Examples](#examples)\n    - [Running in a restricted environment](#running-in-a-restricted-environment)\n  - [Usage as a CLI](#usage-as-a-cli)\n  - [Embedded usage](#embedded-usage)\n  - [Building](#building)\n    - [Docker](#docker)\n      - [Using the Docker file](#using-the-docker-file)\n    - [Make](#make)\n    - [Node](#node)\n  - [How it works](#how-it-works)\n\nForward all your logs to the [Rapid7 Insight Platform](https://www.rapid7.com/products/insight-platform/), like a breeze.\n\n![InsightOps dashboard](https://raw.githubusercontent.com/rapid7/r7insight_docker/master/dashboard.png)\n\n## Arguments\n\n### Mandatory arguments\n\n#### Token\n\nYou can supply the tokens using command line arguments:\n\n- `--logstoken`: Log token for logs\n- `--statstoken`: Log token for stats\n- `--eventstoken`: Log token for events\n- `--token`: Log token which is used for the above tokens if one is not provided.\n  - You can supply only this token and it'll be used for logs, stats and events.\n\nYou can also supply log, stats and event tokens using environment variables.\n\nWhen both command line arguments and environment variables are supplied, the command line arguments are used.\n\n- `INSIGHT_LOGSTOKEN`: Log token for logs\n- `INSIGHT_STATSTOKEN`: Log token for stats\n- `INSIGHT_EVENTSTOKEN`: Log token for events\n- `INSIGHT_TOKEN`: Log token which is used for any of the above tokens if one is not provided.\n  - You can only supply this token and it'll be used for logs, stats and events.\n\n#### Region\n\nYou need to supply the region to forward your logs to with either of these arguments:\n\n- `-r \u003cREGION\u003e`\n- `--region \u003cREGION\u003e`\n\nE.g. `-r 'eu'`\n\n### Optional arguments\n\n- `--no-stats` if you do not want stats to be\npublished to the Rapid7 Insight Platform every second.\n**You need this flag for Docker version \u003c 1.5**\n\n- `--no-logs` if you do not want logs to be published to the Rapid7 Insight Platform.\n\n- `--no-docker-events` if you do not want events to be\npublished to the Rapid7 Insight Platform.\n\n- `-i, --statsinterval \u003cSTATSINTERVAL\u003e` downsamples the logs sent to the Rapid7 Insight Platform.\nIt collects samples and averages them before sending.\n\n- `-a/--add` allows you to add a fixed value to the data being\npublished. This follows the format `\u003cname\u003e=\u003cvalue\u003e`.\n  - If you don't use the `-a` flag, a default value of `host=\"$(uname -n)\"` will be added.\n  - You cannot supply multiple `-a` flags\n\n- `--no-secure` if you want your logs to be sent to the Insight Platform un-encrypted (no TSL/SSL).\n\n- `--log-level` to specify the logging level for the r7insight_docker container itself.\n  - Can also be enabled by specifying the environment variable `INSIGHT_LOG_LEVEL`\n  E.g. `INSIGHT_LOG_LEVEL=info`\n  - By default the logger is silent unless a logger level is defined\n\n#### Filtering\n\nYou can also filter the containers for which logs/stats are forwarded.\n\n##### Notes\n\n- Please ensure you correctly escape the regex pattern since these can be expanded/interpreted by your shell; ideally in single-quotes.\n  - Use `'.*nginx.*'` rather than `.*nginx.*`\n- Do not supply the REGEX pattern in a LEQL fashion as in the UI, filtering is based on normal regular expressions.\n  - Use `'.*nginx.*'`, not `'/.*nginx.*/'`, note the removed foreslashes.\n- For each of the arguments below you can only supply at most one of each.\n  - Use `--skipByName '.*(nginx|haproxy).*'`\n  - Do not use\n\n    ```bash\n    --skipByName '.*nginx.*' --skipByName '.*haproxy.*'\n    ```\n\n##### Filters\n\n- `--matchByName '\u003cREGEX\u003e'`: forward logs/stats only for the containers whose name matches the given `\u003cREGEX\u003e`.\n- `--matchByImage '\u003cREGEX\u003e'`: forward logs/stats only for the containers whose image matches the given `\u003cREGEX\u003e`.\n- `--skipByName '\u003cREGEX\u003e'`: do not forward logs/stats for the containers whose name matches the given `\u003cREGEX\u003e`.\n- `--skipByImage '\u003cREGEX\u003e'`: do not forward logs/stats for the containers whose image matches the given `\u003cREGEX\u003e`.\n\n## Usage as a Container\n\nThe simplest way to forward all your container logs to the Rapid7 Insight Platform is to run this repository as a container.\n\n- If you are using this container in production please ensure that you pin the version of the image.\n  - Use `rapid7/r7insight_docker:1.2.3` rather than `rapid7/r7insight_docker:latest` since `latest` might pull in breaking changes if a new version is released\n  - You can see the the available versions [here](https://hub.docker.com/r/rapid7/r7insight_docker/tags).\n\n### Docker Arguments\n\nThe `--read-only` docker flag specifies that the container file system will be read-only.\nThis is not a requirement but since currently there's no need for writing, it makes the container more secure.\n\nThe `--security-opt=no-new-privileges` docker flag sets a kernel bit which stops the process or its children\nfrom gaining additional privileges via setuid or sgid.\nOnce again not required, but increases security.\n\n### Examples\n\n```bash\ndocker run -v /var/run/docker.sock:/var/run/docker.sock \\\n           --read-only \\\n           --security-opt=no-new-privileges \\\n           rapid7/r7insight_docker \\\n           -t \u003cTOKEN\u003e \\\n           -r \u003cREGION\u003e \\\n           -j \\\n           -a host=\"$(uname -n)\"\n```\n\nYou can also use different tokens for logging, stats and events:\n\n```bash\ndocker run -v /var/run/docker.sock:/var/run/docker.sock \\\n           --read-only \\\n           --security-opt=no-new-privileges \\\n           rapid7/r7insight_docker \\\n           -l \u003cLOGSTOKEN\u003e \\\n           -k \u003cSTATSTOKEN\u003e \\\n           -e \u003cEVENTSTOKEN\u003e \\\n           -r \u003cREGION\u003e \\\n           -j \\\n           -a host=\"$(uname -n)\"\n```\n\n### Running in a restricted environment\n\nSome environments (such as Google Compute Engine) do not allow to access the Docker socket without special privileges.\nYou will get EACCES(`Error: read EACCES`) error if you try to run the container.\nTo run the container in such environments add `--privileged` to the `docker run` command.\n\nExample:\n\n```bash\ndocker run --privileged \\\n           -v /var/run/docker.sock:/var/run/docker.sock \\\n           --read-only \\\n           --security-opt=no-new-privileges \\\n           rapid7/r7insight_docker \\\n           -t \u003cTOKEN\u003e \\\n           -r \u003cREGION\u003e \\\n           -j \\\n           -a host=\"$(uname -n)\"\n```\n\n## Usage as a CLI\n\n```bash\n$ npm install r7insight_docker -g\n$ r7insight_docker -t \"$TOKEN\" -r \"$REGION\" -a host=\"$(uname -n)\"\n```\n\n## Embedded usage\n\nInstall it with: `npm install r7insight_docker --save`\n\nThen, in your JS file:\n\n```javascript\nconst insight = require('r7insight_docker');\n\nconst logger = insight.utils.start({\n  json: false, // or true to parse lines as JSON\n  secure: true, // or false to connect over plain TCP\n  region: \"eu\", // specify region\n  token: process.env.TOKEN, // Insight Platform TOKEN\n  newline: true, // Split on newline delimited entries\n  stats: true, // disable stats if false\n  add: null, // an object whose properties will be added\n\n  // the following options limit the containers being matched\n  // so we can avoid catching logs for unwanted containers\n  matchByName: /hello/, // optional\n  matchByImage: /matteocollina/, //optional\n  skipByName: /.*pasteur.*/, //optional\n  skipByImage: /.*dockerfile.*/ //optional\n});\n\n// logger is the source stream with all the\n// log lines\nsetTimeout(function() {\n  logger.destroy();\n}, 5000);\n```\n\n## Building\n\n### Docker\n\nWe currently release the container on two different bases:\n\n- Node on Debian Bullseye\n- Node on Alpine Linux\n\n#### Using the Docker file\n\nFirst clone this repository, then:\n\n```bash\n# For Debian Bullseye base:\ndocker build -t r7insight_docker .\n# Or for Alpine Linux base:\ndocker build -t r7insight_docker -f alpine.Dockerfile .\n```\n\n### Make\n\nFirstly\n\n```bash\n# For Debian Bullseye base, also the default if not specified:\nexport BUILD_TYPE=node-bullseye\n# Or for Alpine Linux base:\nexport BUILD_TYPE=node-alpine\n```\n\nThen:\n\n```bash\nmake build\nmake test\n```\n\nIf you've build and tested and want to push:\n\n```bash\n# Default is \"rapid7/r7insight_docker\"\nexport DOCKER_REGISTRY_PREFIX=\u003cyour-dockerhub-user\u003e/\u003cyour-image-name\u003e\nmake tag\nmake push\n```\n\n### Node\n\n- Update **package.json** depending on your requirements\n- `make publish`\n\n## How it works\n\nThis module wraps four [Docker\nAPIs](https://docs.docker.com/reference/api/docker_remote_api_v1.17/):\n\n- `POST /containers/{id}/attach`, to fetch the logs\n- `GET /containers/{id}/stats`, to fetch the stats of the container\n- `GET /containers/json`, to detect the containers that are running when\n  this module starts\n- `GET /events`, to detect new containers that will start after the\n  module has started\n\nThis module wraps\n[docker-loghose](https://github.com/mcollina/docker-loghose) and\n[docker-stats](https://github.com/pelger/docker-stats) to fetch the logs\nand the stats as a never ending stream of data.\n\nAll the originating requests are wrapped in a\n[never-ending-stream](https://github.com/mcollina/never-ending-stream).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frapid7%2Fr7insight_docker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frapid7%2Fr7insight_docker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frapid7%2Fr7insight_docker/lists"}