{"id":15013975,"url":"https://github.com/crowdstrike/puppet-falcon","last_synced_at":"2025-08-21T20:32:03.860Z","repository":{"id":41870822,"uuid":"460129765","full_name":"CrowdStrike/puppet-falcon","owner":"CrowdStrike","description":null,"archived":false,"fork":false,"pushed_at":"2024-08-15T17:29:37.000Z","size":129,"stargazers_count":7,"open_issues_count":9,"forks_count":8,"subscribers_count":12,"default_branch":"main","last_synced_at":"2024-12-09T11:06:45.740Z","etag":null,"topics":["puppet"],"latest_commit_sha":null,"homepage":"https://forge.puppet.com/modules/crowdstrike/falcon","language":"Ruby","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/CrowdStrike.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"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":"2022-02-16T18:32:20.000Z","updated_at":"2024-08-15T17:28:03.000Z","dependencies_parsed_at":"2023-02-02T08:02:09.213Z","dependency_job_id":"2ae87755-ed4a-46b9-977e-631bd18cc92c","html_url":"https://github.com/CrowdStrike/puppet-falcon","commit_stats":{"total_commits":73,"total_committers":8,"mean_commits":9.125,"dds":0.3287671232876712,"last_synced_commit":"029aa55359cba8504039a23f4d8002d299f399ee"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CrowdStrike%2Fpuppet-falcon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CrowdStrike%2Fpuppet-falcon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CrowdStrike%2Fpuppet-falcon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CrowdStrike%2Fpuppet-falcon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CrowdStrike","download_url":"https://codeload.github.com/CrowdStrike/puppet-falcon/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230532443,"owners_count":18240792,"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":["puppet"],"created_at":"2024-09-24T19:45:01.226Z","updated_at":"2024-12-20T04:07:01.786Z","avatar_url":"https://github.com/CrowdStrike.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# falcon\n\n## Table of Contents\n\n1. [Description](#description)\n1. [Usage - Configuration options and additional functionality](#usage)\n1. [Limitations - OS compatibility, etc.](#limitations)\n1. [`api` vs `local` install methods](#api-vs-local-install-methods)\n1. [Development - Guide for contributing to the module](#development)\n1. [License](#license)\n\n## Description\n\nThe `falcon` module installs, configures, and manages the `falcon` service across multiple operating systems and distributions.\n\n\u003e **Note**: `puppet-falcon` is an open source project, not a CrowdStrike product. As such, it carries no formal support, expressed or implied.\n\n## Usage\n\nAll parameters for the falcon module are contained within the main `falcon` class. There are many options that will modify what the module does. Refer to [REFERENCE.md](./REFERENCE.md) for more details.\n\nBelow are some of the common use cases.\n\n\u003e **Note**: `falcon` packages are not public so this module has two options for installing the falcon sensor. Using the `install_method` parameter you can choose `api` or `local`. `api` is the default. More information is outlined in [API vs Local install methods](#api-vs-local-install-methods).\n\n### Basic Install, Configure, and Manage the service\n\n```puppet\n# using the `api` method\n\nclass {'falcon':\n\n  client_id     =\u003e Sensitive('12346'),\n  client_secret =\u003e Sensitive('12345'),\n  cid           =\u003e 'AJKQUI123JFKSDFJK`\n}\n```\n\n```puppet\n# using the `local` method\n\n$package_options = {\n  'ensure' =\u003e 'present',\n  'source' =\u003e '/tmp/sensor.rpm'\n  # any other attributes that are valid for the package resource\n}\n\nclass {'falcon':\n  install_method  =\u003e 'local',\n  package_options =\u003e $package_options,\n  cid             =\u003e 'AJKQUI123JFKSDFJK`\n}\n```\n\n---\n\n### Using the `api` install method\n\nThe `api` install methods uses the API to download the sensor package. The version of the package that is downloaded are determined by the parameters passed to the module.\n\nThere are three parameters that alter the behavior of the `api` install method. Only one of these parameters can be used at a time, and they are evaluated in the order they are listed below.\n\n- `version` - Will download the sensor package matching the version you specify.\n- `update_policy` - Will download the version specified by the update policy.\n- `version_decrement` - Will download the `n`th version before the current version.\n\nThe drawbacks to using the `api` install method are outlined in [API vs Local install methods](#api-vs-local-install-methods).\n\nExamples for each are below.\n**Using the `version` parameter**\n\nThis takes precedence over `update_policy` and `version_decrement`.\n\n```puppet\nclass { 'falcon':\n  client_id     =\u003e Sensitive('12346'),\n  client_secret =\u003e Sensitive('12345'),\n  version       =\u003e '1.0.0',\n  cid           =\u003e 'AJKQUI123JFKSDFJK`\n}\n```\n\n**Using the `update_policy` parameter**\n\nThis takes precedence over the `version_decrement` parameter.\n\n```puppet\nclass { 'falcon':\n  client_id     =\u003e Sensitive('12346'),\n  client_secret =\u003e Sensitive('12345'),\n  update_policy =\u003e 'platform_default',\n  cid           =\u003e 'AJKQUI123JFKSDFJK`\n}\n```\n\n**Using the `version_decrement` parameter**\n\nUse `version_decrement` to download the `n-x` version.\n\nA value of `0` will download the latest version, and a value of `2` will download the `n-2` version (`2` releases behind latest).\n\n```puppet\nclass { 'falcon':\n  client_id         =\u003e Sensitive('12346'),\n  client_secret     =\u003e Sensitive('12345'),\n  version_decrement =\u003e 2,\n  cid               =\u003e 'AJKQUI123JFKSDFJK`\n}\n```\n\n---\n\n### Using the `local` install method\n\nThe `local` install method gives you full control on how the sensor is installed.\n\nSome reasons you may use this method are:\n\n- You want to install the sensor from a local file\n- You have your own package management system\n\nYou can learn more about the `local` install method in [API vs Local install methods](#api-vs-local-install-methods).\n\nWhen you use the `local` install method, `package_options` is required. Parameters in `package_options` are passed to the the `package` resource. You must provide any required parameters for the `package` resource except the `name` parameter. The module will pick the appropriate name based on the operating system. You can still override the name by specifying the `name` property in the `package_options` hash.\n\n```puppet\n# Using a local file\n\nfile {'/tmp/sensor.rpm':\n  ensure =\u003e 'present',\n  source =\u003e 'https://company-filer-server.com/sensor.rpm'\n}\n\nclass {'falcon':\n  install_method =\u003e 'local',\n  package_options =\u003e {\n    'ensure' =\u003e 'present',\n    'source' =\u003e '/tmp/sensor.rpm'\n  },\n  require =\u003e File['/tmp/sensor.rpm']\n}\n```\n\n```puppet\n# Using a http source\n\nclass {'falcon':\n  install_method =\u003e 'local',\n  package_options =\u003e {\n    'ensure' =\u003e 'present',\n    'source' =\u003e 'http://example.com/sensor.rpm'\n  }\n}\n```\n\n```puppet\n# Overriding the name parameter\n\nclass {'falcon':\n  install_method =\u003e 'local',\n  package_options =\u003e {\n    'ensure' =\u003e 'present',\n    'source' =\u003e '/tmp/sensor.rpm',\n    'name'   =\u003e 'falcon-sensor'\n  }\n}\n```\n\n---\n\n### Removing the Installer file\n\nWhen `install_method` is `api` you can use the `cleanup_installer` parameter to remove the installer file after installation.\n\n```puppet\nclass { 'falcon':\n  client_id         =\u003e Sensitive('12346'),\n  client_secret     =\u003e Sensitive('12345'),\n  cleanup_installer =\u003e true,\n  cid               =\u003e 'AJKQUI123JFKSDFJK`\n}\n```\n\n---\n\n### Overriding the default Package parameters\n\nYou can override any parameter that is passed to the `package` resource using the `package_options` parameter. [Valid Package Parameters](https://puppet.com/docs/puppet/7/types/package.html)\n\nThis works the same in both `api` and `local` install methods.\n\n```puppet\n$package_options = {\n  'provider' =\u003e 'rpm',\n  'install_options' =\u003e '--force',\n}\n\nclass { 'falcon':\n  package_options =\u003e $package_options\n}\n```\n\n---\n\n### Opt out of the module installing the package\n\n```puppet\nclass {'falcon':\n  package_manage =\u003e false\n  # ... other required params\n}\n```\n\n---\n\n### Opt out of the module configuring the agent - _Linux Only_\n\n\u003e **Note** The windows agent can only be configured at install time. The Linux agent ships with `falconctl` that allows puppet to configure the agent after install. For example: updating the `cid` property in your resource will update the `cid` on the linux agent on the next run, but not the windows.\n\n```puppet\nclass {'falcon':\n  config_manage =\u003e false\n  # ... other required params\n}\n```\n\n---\n\n### Opt out of the module controlling the service\n\n```puppet\nclass {'falcon':\n  service_manage =\u003e false\n  # ... other required params\n}\n```\n\n---\n\n### Registering a `cid`\n\n```puppet\nclass {'falcon':\n  cid =\u003e 'AJKQUI123JFKSDFJK`\n  # ... other required params\n}\n```\n\n---\n\n### Registering a `cid` with a provisioning token\n\nIf your company requires a provisioning token to register a agent, you can use the `provisioning_token` parameter.\n\n```puppet\nclass {'falcon':\n  cid                =\u003e 'AJKQUI123JFKSDFJK`,\n  provisioning_token =\u003e '1234567890'\n  # ... other required params\n}\n```\n\n### Setting proxy settings\n\nYou can use the `proxy_host`, `proxy_port`, and `proxy_enabled` parameters to configure proxy settings for your agent.\n\n\u003e **Note** Mac installs have no proxy settings specific to the agent. Instead it uses the OS's proxy settings. Passing values to these parameters won't configure any proxy settings for Mac.\n\nclass {'falcon':\n  cid                =\u003e 'AJKQUI123JFKSDFJK`,\n  provisioning_token =\u003e '1234567890,'\n  proxy_host         =\u003e 'neptune.example.com',\n  proxy_port         =\u003e '8080',\n  proxy_enabled      =\u003e true\n  # ... other required params\n}\n\n---\n\n### Pinning the agent version\n\nIf you want to pin the agent version to a specific version using the `api` install method then you can set `version_manage` to true.\n\nIn our example below we use `version_decrement`, but it works the same for all. Puppet will consult the API to determine what version `version_decrement =\u003e 2` resolves to. It then will download that version and ensure it is installed.\n\nEach subsequent run it will check the api to see if the version returned is the one installed. If for example, a new version is released it would cause the version returned from the check to change causing the agent to be upgraded to the new `n-2` version.\n\n\u003e **warning**: This causes the module to consult the API every run to ensure the version the API returns is the version that is installed. This could cause rate limit issues for large deployments. If you want to have automated upgrades/downgrades and use the `api` install method it is generally suggested to set `version_manage` to `false` and allow the CrowdStrike Update Policy to do the upgrades/downgrades instead of Puppet.\n\n```puppet\nclass {'falcon':\n  version_manage =\u003e true\n  client_id      =\u003e Sensitive('12346'),\n  client_secret  =\u003e Sensitive('12345'),\n  update_policy  =\u003e 'platform_default'\n  cid            =\u003e 'AJKQUI123JFKSDFJK`\n  # ... other required params\n}\n```\n\nUsing the `install_method` of `local`\n\n```puppet\nclass {'falcon':\n  install_method =\u003e 'local',\n  package_options =\u003e {\n    'ensure' =\u003e '32.4.3',\n    'source' =\u003e '/tmp/sensor-32.4.3.rpm'\n  }\n}\n```\n\n---\n\n## `api` vs `local` install methods\n\nGenerally the `api` method will be fine for most use cases if `version_manage` is set to `false`. If `version_manage` is set to `true` you may run into api rate limits.\n\nYou can use `local` install method if you want full control and don't want to leverage the API.\n\n---\n\n### Why are there two install methods?\n\nGenerally Puppet modules that manage a package control the full lifecycle of that package from installation to removal. The fact CrowdStrike agent packages are not public makes this hard.\n\nWe still wanted to give a hands off way of quickly getting a package installed so we created the `api` install method. This method will require you to provide api credentials, and then we will download the correct package version from the CrowdStrike API. There are parameters that let you control the behavior like setting `update_policy`. This will cause the module to download the correct version based on what the update policy suggests. [Examples of each here](#using-the-api-install-method).\n\nHowever, this method might not be suitable for everyone so the `local` install method was created that gives you full control on how the sensor is installed.\n\n---\n\n### How the `api` install method works\n\nThe api install method will use the falcon api to download the correct package version. The correct package version depends on what parameters you provide. You can see [Examples of each here](#using-the-api-install-method).\n\nThe first run will cause Puppet to call the appropriate CrowdStrike apis to get the information needed to download the sensor package. It will then download the sensor package. After that, normal puppet resources take over.\n\nIf you set `version_manage` to `true` every run will cause the module to consult the CrowdStrike API to get the appropriate package version. Then it will determine if the installed version is the same as the returned version. If they are not the same, then it will download the correct package version and do the appropriate install/update/downgrade actions.\n\nIf you set `version_manage` to `false` then api calls will only happen when the CrowdStrike sensor is not installed.\n\n---\n\n### API rate limits\n\nThe main limitation of the `api` install method is api rate limits. We haven't hit them ourselves, but it may be possible for large installations to hit a rate limit when using the `api` install method with `version_manage` set to `true`.\n\nEach time Puppet compiles a catalog for a node it uses the API to determine what version of the agent should be installed. If the agent is already on the correct version then no further apis calls are made.\n\nSetting `version_manage` to `false` will prevent any api calls unless the agent is not installed.\n\n---\n\n### Reducing API calls\n\nThe best way to reduce API calls is to set `version_manage` to `false`. This will ensure the only time the API is called is when the agent is not installed. This should prevent API rate limit issues.\n\n---\n\n## Installing on MacOS\n\nApple platforms require a Mobile Device Management (MDM) profile to install kernel extensions without user prompting. Because of this limitation, this module will only download and install the Falcon Sensor. The Mac deployment guide in the CrowdStrike documentation outlines the steps required to configure the Mac sensor to start reporting to a `CID`.\n\n## Development\n\nIf you want to develop new content or improve on this collection, please open an issue or create a pull request. All contributions are welcome!\n\n## License\n\nSee the [LICENSE](LICENSE) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrowdstrike%2Fpuppet-falcon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcrowdstrike%2Fpuppet-falcon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrowdstrike%2Fpuppet-falcon/lists"}