{"id":13787805,"url":"https://github.com/falcosecurity/falcoctl","last_synced_at":"2026-01-21T16:04:38.827Z","repository":{"id":35176432,"uuid":"205468623","full_name":"falcosecurity/falcoctl","owner":"falcosecurity","description":"Administrative tooling for Falco","archived":false,"fork":false,"pushed_at":"2024-04-12T08:17:34.000Z","size":14513,"stargazers_count":81,"open_issues_count":11,"forks_count":52,"subscribers_count":16,"default_branch":"main","last_synced_at":"2024-04-12T15:04:51.090Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","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/falcosecurity.png","metadata":{"files":{"readme":"README.md","changelog":null,"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}},"created_at":"2019-08-30T23:13:43.000Z","updated_at":"2024-05-28T08:21:01.128Z","dependencies_parsed_at":"2023-10-15T08:04:08.550Z","dependency_job_id":"80a45805-7308-4b3f-ab1e-30727fc7a0e8","html_url":"https://github.com/falcosecurity/falcoctl","commit_stats":{"total_commits":456,"total_committers":23,"mean_commits":19.82608695652174,"dds":0.6337719298245614,"last_synced_commit":"ddffd44393406e697806e3f0a3dc61b6f24afd6b"},"previous_names":[],"tags_count":52,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/falcosecurity%2Ffalcoctl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/falcosecurity%2Ffalcoctl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/falcosecurity%2Ffalcoctl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/falcosecurity%2Ffalcoctl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/falcosecurity","download_url":"https://codeload.github.com/falcosecurity/falcoctl/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247157283,"owners_count":20893220,"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-08-03T21:00:31.588Z","updated_at":"2026-01-21T16:04:38.816Z","avatar_url":"https://github.com/falcosecurity.png","language":"Go","funding_links":[],"categories":["Official projects"],"sub_categories":["Repositories"],"readme":"# 🧰 falcoctl\n\n[![Falco Core Repository](https://github.com/falcosecurity/evolution/blob/main/repos/badges/falco-core-blue.svg)](https://github.com/falcosecurity/evolution/blob/main/REPOSITORIES.md#core-scope) [![Stable](https://img.shields.io/badge/status-stable-brightgreen?style=for-the-badge)](https://github.com/falcosecurity/evolution/blob/main/REPOSITORIES.md#stable) [![License](https://img.shields.io/github/license/falcosecurity/falcoctl?style=for-the-badge)](./LICENSE)\n\nThe official CLI tool for working with [Falco](https://github.com/falcosecurity/falco) and its [ecosystem components](https://falco.org/docs/#what-are-the-ecosystem-projects-that-can-interact-with-falco).\n\n## Installation\n### Install falcoctl manually\nYou can download and install *falcoctl* manually following the appropriate instructions based on your operating system architecture.\n#### Linux\n##### AMD64\n```bash\nLATEST=$(curl -sI https://github.com/falcosecurity/falcoctl/releases/latest | awk '/location: /{gsub(\"\\r\",\"\",$2);split($2,v,\"/\");print substr(v[8],2)}')\ncurl --fail -LS \"https://github.com/falcosecurity/falcoctl/releases/download/v${LATEST}/falcoctl_${LATEST}_linux_amd64.tar.gz\" | tar -xz\nsudo install -o root -g root -m 0755 falcoctl /usr/local/bin/falcoctl\n```\n##### ARM64\n```bash\nLATEST=$(curl -sI https://github.com/falcosecurity/falcoctl/releases/latest | awk '/location: /{gsub(\"\\r\",\"\",$2);split($2,v,\"/\");print substr(v[8],2)}')\ncurl --fail -LS \"https://github.com/falcosecurity/falcoctl/releases/download/v${LATEST}/falcoctl_${LATEST}_linux_arm64.tar.gz\" | tar -xz\nsudo install -o root -g root -m 0755 falcoctl /usr/local/bin/falcoctl\n```\n\u003e NOTE: Make sure */usr/local/bin* is in your PATH environment variable.\n\n#### MacOS\nThe easiest way to install on MacOS is via `Homebrew`:\n```bash\nbrew install falcoctl\n```\n\nAlternatively, you can download directly from the source:\n\n##### Intel\n```bash\nLATEST=$(curl -sI https://github.com/falcosecurity/falcoctl/releases/latest | awk '/location: /{gsub(\"\\r\",\"\",$2);split($2,v,\"/\");print substr(v[8],2)}')\ncurl --fail -LS \"https://github.com/falcosecurity/falcoctl/releases/download/v${LATEST}/falcoctl_${LATEST}_darwin_amd64.tar.gz\" | tar -xz\nchmod +x falcoctl\nsudo mv falcoctl /usr/local/bin/falcoctl\n```\n##### Apple Silicon\n```bash\nLATEST=$(curl -sI https://github.com/falcosecurity/falcoctl/releases/latest | awk '/location: /{gsub(\"\\r\",\"\",$2);split($2,v,\"/\");print substr(v[8],2)}')\ncurl --fail -LS \"https://github.com/falcosecurity/falcoctl/releases/download/v${LATEST}/falcoctl_${LATEST}_darwin_arm64.tar.gz\" | tar -xz\nchmod +x falcoctl\nsudo mv falcoctl /usr/local/bin/falcoctl\n```\n\nAlternatively, you can manually download *falcoctl* from the [falcoctl releases](https://github.com/falcosecurity/falcoctl/releases) page on GitHub.\n\n### Install falcoctl from source\nYou can install *falcoctl* from source. First thing clone the *falcoctl* repository, build the *falcoctl* binary, and move it to a file location in your system **PATH**.\n```bash\ngit clone https://github.com/falcosecurity/falcoctl.git\ncd falcoctl\nmake falcoctl\nsudo mv falcoctl /usr/local/bin/falcoctl\n```\n\n# Getting Started\n\n## Installing an artifact\n\nThis tutorial aims at presenting how to install a Falco artifact. The next few steps will present us with the fundamental commands of *falcoctl* and how to use them.\n\nFirst thing, we need to add a new `index` to *falcoctl*:\n```bash\n$ falcoctl index add falcosecurity https://falcosecurity.github.io/falcoctl/index.yaml\n```\nWe just downloaded the metadata of the **artifacts** hosted and distributed by the **falcosecurity** organization and made them available to the *falcoctl* tool.\nNow let's check that the `index` file is in place by running:\n```\n$ falcoctl index list\n```\nWe should get an output similar to this one:\n```\nNAME            URL                                                     ADDED                   UPDATED            \nfalcosecurity   https://falcosecurity.github.io/falcoctl/index.yaml     2022-10-25 15:01:25     2022-10-25 15:01:25\n```\nNow let's search all the artifacts related to *cloudtrail*:\n```\n$ falcoctl artifact search cloudtrail\nINDEX           ARTIFACT                TYPE            REGISTRY        REPOSITORY                              \nfalcosecurity   cloudtrail              plugin          ghcr.io         falcosecurity/plugins/plugin/cloudtrail \nfalcosecurity   cloudtrail-rules        rulesfile       ghcr.io         falcosecurity/plugins/ruleset/cloudtrail\n```\nLets install the *cloudtrail plugin*:\n```\n$ falcoctl artifact install cloudtrail --plugins-dir=./\n INFO  Reading all configured index files from \"/home/aldo/.config/falcoctl/indexes.yaml\"\n INFO  Preparing to pull \"ghcr.io/falcosecurity/plugins/plugin/cloudtrail:latest\"\n INFO  Remote registry \"ghcr.io\" implements docker registry API V2\n INFO  Pulling 44136fa355b3: ############################################# 100% \n INFO  Pulling 80e0c33f30c0: ############################################# 100% \n INFO  Pulling b024dd7a2a63: ############################################# 100% \n INFO  Artifact successfully installed in \"./\" \n```\nInstall the *cloudtrail-rules* rulesfile:\n```\n$ ./falcoctl artifact install cloudtrail-rules --rulesfiles-dir=./\n INFO  Reading all configured index files from \"/home/aldo/.config/falcoctl/indexes.yaml\"\n INFO  Preparing to pull \"ghcr.io/falcosecurity/plugins/ruleset/cloudtrail:latest\"\n INFO  Remote registry \"ghcr.io\" implements docker registry API V2\n INFO  Pulling 44136fa355b3: ############################################# 100% \n INFO  Pulling e0dccb7b0f1d: ############################################# 100% \n INFO  Pulling 575bced78731: ############################################# 100% \n INFO  Artifact successfully installed in \"./\"\n```\n\nWe should have now two new files in the current directory: `aws_cloudtrail_rules.yaml` and `libcloudtrail.so`.\n\n# Falcoctl Configuration Files\n\n## `/etc/falcoctl/falcoctl.yaml`\n\nThe `falco configuration file` is a yaml file that contains some metadata about the `falcoctl` behaviour.\nIt contains the list of the indexes where the artifacts are listed, how often and which artifacts needed to be updated periodically.\nThe default configuration is stored in `/etc/falcoctl/falcoctl.yaml`.\nThis is an example of a falcoctl configuration file:\n\n``` yaml\nartifact:\n  follow:\n    every: 6h0m0s\n    falcoVersions: http://localhost:8765/versions\n    refs:\n    - falco-rules:0\n    - my-rules:1\n    rulesfilesdir: /tmp/rules\n    pluginsdir: /tmp/plugins\n    statedir: /tmp/state\n  install:\n    refs:\n      - cloudtrail-rules:latest\n      - cloudtrail:latest\n    rulesfilesdir: /tmp/rules\n    pluginsdir: /tmp/plugins\n    statedir: /tmp/state\nindexes:\n- name: falcosecurity\n  url: https://falcosecurity.github.io/falcoctl/index.yaml\n- name: my-index\n  url: https://example.com/falcoctl/index.yaml\nregistry:\n  auth:\n    basic:\n    - password: password\n      registry: myregistry.example.com:5000\n      user: user\n    oauth:\n    - registry: myregistry.example.com:5001\n      clientsecret: \"999999\"\n      clientid: \"000000\"\n      tokenurl: http://myregistry.example.com:9096/token\n    gcp:\n    - registry: europe-docker.pkg.dev\n```\n\n## `~/.config/falcoctl/`\n\nThe `~/.config/falcoctl/` directory contains:\n- *cache objects*\n- *OAuth2 client credentials*\n\n### `~/.config/falcoctl/indexes.yaml`\n\nThis file is used for cache purposes and contains the *index refs* added by the command `falcoctl index add [name] [ref]`. The *index ref* is enriched with two timestamps to track when it was added and the last time is was updated. Once the *index ref* is added, `falcoctl` will download the real index in the `~/.config/falcoctl/indexes/` directory. Moreover, every time the index is fetched, the `updated_timestamp` is updated.\n\n### `~/.config/falcoctl/clientcredentials.json`\n\nThe command `falcoctl registry auth oauth` will add the `clientcredentials.json` file to the `~/.config/falcoctl/` directory. That file will contain all the needed information for the OAuth2 authetication.\n\n# Falcoctl Commands\n\n## Falcoctl index\n\nThe `index` file is a yaml file that contains some metadata about the Falco **artifacts**. Each entry carries information such as the name, type, registry, repository and other info for the given **artifact**. Different *falcoctl* commands rely on the metadata contained in the `index` file for their operation.\nThis is an example of an index file:\n```yaml\n- name: okta\n  type: plugin\n  registry: ghcr.io\n  repository: falcosecurity/plugins/plugin/okta\n  description: Okta Log Events\n  home: https://github.com/falcosecurity/plugins/tree/master/plugins/okta\n  keywords:\n    - audit\n    - log-events\n    - okta\n  license: Apache-2.0\n  maintainers:\n    - email: cncf-falco-dev@lists.cncf.io\n      name: The Falco Authors\n  sources:\n    - https://github.com/falcosecurity/plugins/tree/master/plugins/okta\n- name: okta-rules\n  type: rulesfile\n  registry: ghcr.io\n  repository: falcosecurity/plugins/ruleset/okta\n  description: Okta Log Events\n  home: https://github.com/falcosecurity/plugins/tree/master/plugins/okta\n  keywords:\n    - audit\n    - log-events\n    - okta\n    - okta-rules\n  license: Apache-2.0\n  maintainers:\n    - email: cncf-falco-dev@lists.cncf.io\n      name: The Falco Authors\n  sources:\n    - https://github.com/falcosecurity/plugins/tree/master/plugins/okta/rules\n```\n\n### Index Storage Backends\n\nIndices for *falcoctl* can be retrieved from various storage backends. The supported index storage backends are listed in the table below. Note if you do not specify a backend type when adding a new index *falcoctl* will try to guess based on the `URI Scheme`:\n\n| Name  | URI Scheme | Description                                                                                   |\n| ----- | ---------- | --------------------------------------------------------------------------------------------- |\n| http  | http://    | Can be used to retrieve indices via simple HTTP GET requests.                                 |\n| https | https://   | Convenience alias for the HTTP backend.                                                       |\n| gcs   | gs://      | For indices stored as Google Cloud Storage objects. Supports application default credentials. |\n| file  | file://    | For indices stored on the local file system.                                                  |\n| s3    | s3://      | For indices stored as AWS S3 objects. Supports default credentials, IRSA.                     |\n\n\n#### falcoctl index add\nNew indexes are configured to be used by the *falcoctl* tool by adding them through the `index add` command. There are no limits to the number of indexes that can be added to the *falcoctl* tool. When adding a new index the tool adds a new entry in a file called **indexes.yaml** and downloads the *index* file in `~/.config/falcoctl`. The same folder is used to store the **indexes.yaml** file, too.\nThe following command adds a new index named *falcosecurity*:\n```bash\n$ falcoctl index add falcosecurity https://falcosecurity.github.io/falcoctl/index.yaml\n```\n\nThe following command adds the same index *falcosecurity*, but explicitly sets the storage backend to `https`:\n```bash\n$ falcoctl index add falcosecurity https://falcosecurity.github.io/falcoctl/index.yaml https\n```\n#### falcoctl index list\nUsing the `index list` command you can check the configured `indexes` in your local system:\n```bash\n$ falcoctl index list\nNAME            URL                                                     ADDED                   UPDATED            \n$ falcosecurity   https://falcosecurity.github.io/falcoctl/index.yaml     2022-10-25 15:01:25     2022-10-25 15:01:25\n```\n#### falcoctl index update\nThe `index update` allows to update a previously configured `index` file by syncing the local one with the remote one:\n```bash\n$ falcoctl index update falcosecurity\n```\n#### falcoctl index remove\nWhen we want to remove an `index` file that we configured previously, the `index remove` command is the one we need:\n```bash\n$ falcoctl index remove falcosecurity\n```\nThe above command will remove the **falcosecurity** index from the local system.\n\n## Falcoctl artifact\nThe *falcoctl* tool provides different commands to interact with Falco **artifacts**. It makes easy to *search*, *install* and get *info* for the **artifacts** provided by a given `index` file. For these commands to properly work we need to configure at least an `index` file in our system as shown in the previus section.\n\n### Artifact References and Versions\n\nFalcoctl supports multiple ways to reference artifacts. Understanding these formats is essential for installing, pushing, and managing artifacts.\n\n#### Reference Formats\n\n| Format | Example | Description |\n| ------ | ------- | ----------- |\n| Simple name | `cloudtrail` | Artifact name only. Requires an index to resolve the full OCI reference. Defaults to `latest` tag. |\n| Simple name with tag | `cloudtrail:0.6.0` | Artifact name with version tag. Requires an index to resolve the full OCI reference. |\n| Full OCI reference | `ghcr.io/falcosecurity/plugins/plugin/cloudtrail:latest` | Complete registry/repository path with tag. Bypasses the index entirely. |\n| Full OCI reference with digest | `ghcr.io/falcosecurity/plugins/plugin/cloudtrail@sha256:abc123...` | Complete reference with content digest. Immutable reference to a specific artifact. |\n\n#### How Reference Resolution Works\n\nWhen you use a **simple name** (e.g., `cloudtrail` or `cloudtrail:0.6.0`), falcoctl:\n1. Searches configured index files for a matching artifact name\n2. Uses the index entry to build the full OCI reference (registry + repository)\n3. Appends the tag (or `latest` if not specified)\n\nWhen you use a **full OCI reference** (e.g., `ghcr.io/myregistry/myartifact:1.0.0`), falcoctl:\n1. Uses the reference directly without consulting any index\n2. Pulls directly from the specified registry and repository\n\n#### OCI Tags vs Artifact Version\n\nIt's important to understand the difference between the **OCI tag** and the **artifact version**:\n\n| Concept | Example | Purpose |\n| ------- | ------- | ------- |\n| OCI Tag | `:latest`, `:0.6.0`, `:stable` | Identifies the artifact in the registry. Can be any string. Mutable (can be moved to different content). |\n| Artifact Version | `--version \"1.0.0\"` | Stored in the artifact's config layer metadata. Must be valid semver. Used for dependency resolution. |\n\n**Example:** An artifact pushed as `myregistry/myrules:latest` with `--version \"2.0.0\"` has:\n- OCI tag: `latest` (used to pull the artifact)\n- Artifact version: `2.0.0` (used for dependency resolution and compatibility checks)\n\n#### Version Requirements\n\nWhen **pushing** artifacts with `falcoctl registry push`:\n- The `--version` flag is **required**\n- Must be a valid [Semantic Version](https://semver.org/) (e.g., `1.0.0`, `2.1.3-rc1`)\n- Short versions like `1` or `1.0` are **not valid** and will be rejected\n- The version is stored in the artifact's OCI config layer\n\nWhen **installing** artifacts with `falcoctl artifact install`:\n- The tool accepts **tolerant semver formats** for maximum flexibility:\n  - Full semver: `1.2.3`, `0.6.0`\n  - Major-only: `1`, `4`, `0` (normalized to `1.0.0`, `4.0.0`, `0.0.0`)\n  - Major.minor: `1.2`, `0.6` (normalized to `1.2.0`, `0.6.0`)\n  - With v-prefix: `v1.2.3` (normalized to `1.2.3`)\n- The version in the artifact's config layer is used for dependency resolution\n- If multiple artifacts depend on different versions of the same dependency, the highest compatible version is selected\n- Major version mismatches between dependencies will cause an error\n\n**Note:** This tolerant parsing allows you to pin to major versions (e.g., `falco-rules:0` or `custom-rules:1`) and the tool automatically handles version normalization.\n\n#### Examples\n\n**Install using simple name (uses index):**\n```bash\n# Installs latest version\n$ falcoctl artifact install cloudtrail\n\n# Installs specific version (tag)\n$ falcoctl artifact install cloudtrail:0.6.0\n\n# Installs using major-only version\n$ falcoctl artifact install falco-rules:0\n$ falcoctl artifact install cloudtrail:1\n```\n\n**Install using full OCI reference (bypasses index):**\n```bash\n# Using tag\n$ falcoctl artifact install ghcr.io/falcosecurity/plugins/plugin/cloudtrail:latest\n\n# Using digest (immutable)\n$ falcoctl artifact install ghcr.io/falcosecurity/plugins/plugin/cloudtrail@sha256:abc123...\n```\n\n**Push with proper versioning:**\n```bash\n# Push with semver version (stored in metadata) and OCI tag\n$ falcoctl registry push --type rulesfile --version \"1.0.0\" \\\n    ghcr.io/myregistry/myrules:latest myrules.tar.gz\n\n# Push with floating tags for major/minor versions\n$ falcoctl registry push --type rulesfile --version \"1.2.3\" \\\n    --add-floating-tags ghcr.io/myregistry/myrules:1.2.3 myrules.tar.gz\n# This creates tags: 1.2.3, 1.2, 1\n```\n\n#### Falcoctl artifact search\nThe `artifact search` command allows to search for **artifacts** provided by the `index` files configured in *falcoctl*. The command supports searches by name or by keywords and displays all the **artifacts** that match the search. Assuming that we have already configured the `index` provided by the `falcosecurity` organization, the following command shows all the **artifacts** that work with **Kubernetes**:\n```bash\n$ falcoctl artifact search kubernetes\nINDEX           ARTIFACT        TYPE            REGISTRY        REPOSITORY                            \nfalcosecurity   k8saudit        plugin          ghcr.io         falcosecurity/plugins/plugin/k8saudit \nfalcosecurity   k8saudit-rules  rulesfile       ghcr.io         falcosecurity/plugins/ruleset/k8saudit\n```\n\n#### Falcoctl artifact info\nAs per the name, `artifact info` prints some info for a given **artifact**:\n```bash\n$ falcoctl artifact info k8saudit\nREF                                             TAGS                                          \nghcr.io/falcosecurity/plugins/plugin/k8saudit   0.1.0 0.2.0 0.2.1 0.3.0 0.4.0-rc1 0.4.0 latest\n```\nIt shows the OCI **reference** and **tags** for the **artifact** of interest. Thot info is usually used with other commands.\n\n#### Falcoctl artifact install\nThe above commands help us to find all the necessary info for a given **artifact**. The `artifact install` command installs an **artifact**. It pulls the **artifact** from remote repository, and saves it in a given directory. The following command installs the *k8saudit* plugin in the default path:\n```bash\n$ falcoctl artifact install k8saudit\n INFO  Reading all configured index files from \"/home/aldo/.config/falcoctl/indexes.yaml\"\n INFO  Preparing to pull \"ghcr.io/falcosecurity/plugins/plugin/k8saudit:latest\"\n INFO  Remote registry \"ghcr.io\" implements docker registry API V2                                                                                                                                              \n INFO  Pulling 44136fa355b3: ############################################# 100% \n INFO  Pulling ded0b5419f40: ############################################# 100% \n INFO  Pulling 107d1230f3f0: ############################################# 100% \n INFO  Artifact successfully installed in \"/usr/share/falco/plugins\"\n```\n\nBy default, if we give the name of an **artifact** it will search for the **artifact** in the configured `index` files and downlaod the `latest` version. The commands accepts also the OCI **reference** of an **artifact**. In this case, it will ignore the local `index` files.\n The command has two flags:\n * `--plugins-dir`: directory where to install plugins. Defaults to `/usr/share/falco/plugins`;\n * `--rulesfiles-dir`: directory where to install rules. Defaults to `/etc/falco`.\n\n \u003e If the repositories of the **artifacts** your are trying to install are not public then you need to authenticate to the remote registry.\n\n##### Handling Multiple Versions\n\nStarting from version `v0.12.0`, when multiple versions of the same artifact are specified (e.g., `falcoctl artifact install foo:1.0.0 foo:2.0.0`), the command will automatically keep only the **highest version** and discard the others. A warning message will be displayed to inform you which version was kept and which were discarded. This behavior also applies when resolving dependencies: if different artifacts require different versions of the same dependency, the highest compatible version will be selected.\n\n#### Falcoctl artifact follow\nThe above commands allow us to keep up-to-date one or more given **artifacts**. The `artifact follow` command checks for updates on a periodic basis and then downloads and installs the latest version, as specified by the passed tags. \nIt pulls the **artifact** from remote repository, and saves it in a given directory. The following command installs the *github-rules* rulesfile in the default path:\n```bash\n $ falcoctl artifact follow github-rules\n WARN  falcosecurity already exists with the same configuration, skipping\n INFO  Reading all configured index files from \"/root/.config/falcoctl/indexes.yaml\"\nINFO: Creating follower for \"github-rules\", with check every 6h0m0s\n INFO  Starting follower for \"ghcr.io/falcosecurity/plugins/ruleset/github:latest\"\n INFO   (ghcr.io/falcosecurity/plugins/ruleset/github:latest) found new version under tag \"latest\"\n INFO   (ghcr.io/falcosecurity/plugins/ruleset/github:latest) artifact with tag \"latest\" correctly installed\n\n```\n\nBy default, if we give the name of an **artifact** it will search for the **artifact** in the configured `index` files and downlaod the `latest` version. The commands accepts also the OCI **reference** of an **artifact**. In this case, it will ignore the local `index` files.\n The command can specify the directory where to install the *rulesfile* artifacts through the `--rulesfiles-dir` flag (defaults to `/etc/falco`).\n\n \u003e If the repositories of the **artifacts** your are trying to install are not public then you need to authenticate to the remote registry.\n \n \u003e Please note that only **rulesfile** artifact can be followed.\n\n ## Falcoctl registry\n\n The `registry` commands interact with OCI registries allowing the user to authenticate, pull and push artifacts. We have tested the *falcoctl* tool with the **ghcr.io** registry, but it should work with all the registries that support the OCI artifacts.\n\n### Falcoctl registry auth\nThe `registry auth` command authenticates a user to a given OCI registry.\n\n#### Falcoctl registry auth basic\nThe `registry auth basic` command authenticates a user to a given OCI registry using HTTP Basic Authentication. Run the command in advance for any private registries.\n\n#### Falcoctl registry auth oauth\nThe `registry auth oauth` command retrieves access and refresh tokens for OAuth2.0 client credentials flow authentication. Run the command in advance for any private registries.\n\n#### Falcoctl registry auth gcp\nThe `registry auth gcp` command retrieves access tokens using [Application Default Credentials](https://cloud.google.com/docs/authentication/application-default-credentials). In particular, it supports access token retrieval using Google Compute Engine metadata server and Workload Identity, useful to authenticate your deployed Falco workloads. Run the command in advance for Artifact Registry authentication.\n\nTwo typical use cases:\n\n1. You are manipulating some rules or plugins and use `falcoctl` to pull or push to an Artifact Registry:\n   1. run `gcloud auth application-default login` to generate a JSON credential file that will be used by applications.\n   2. run `falcoctl registry auth gcp europe-docker.pkg.dev` for instance to use Application Default Credentials to connect to any repository hosted at `europe-docker.pkg.dev`.\n2. You have a Falco instance with Falcoctl as a side car, running in a GKE cluster with Workload Identity enabled:\n   1. Workload Identity is correctly set up for the Falco instance (see the [documentation](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity)).\n   2. Add an environment variable like `FALCOCTL_REGISTRY_AUTH_GCP=europe-docker.pkg.dev` to enable GCP authentication for the `europe-docker.pkg.dev` registry.\n   3. The Falcoctl instance will get access tokens from the metadata server and use them to authenticate to the registry and download your rules.\n\n### Falcoctl registry push\nIt pushes local files and references the artifact uniquely. The following command shows how to push a local file to a remote registry:\n```bash\n$ falcoctl registry push --type=plugin --version \"0.3.0\" ghcr.io/falcosecurity/plugins/plugin/cloudtrail:0.3.0 clouddrail-0.3.0-linux-x86_64.tar.gz --platform linux/amd64\n```\nThe type denotes the **artifact** type in this case *plugins*. The `ghcr.io/falcosecurity/plugins/plugin/cloudtrail:0.3.0` is the unique reference that points to the **artifact**.\nCurrently, *falcoctl* supports only two types of artifacts: **plugin** and **rulesfile**. Based on **artifact type** the commands accepts different flags:\n* `--add-floating-tags`: add the floating tags for the major and minor versions\n* `--annotation-source`: set annotation source for the artifact;\n* `--depends-on`: set an artifact dependency (can be specified multiple times). Example: `--depends-on my-plugin:1.2.3`\n* `--tag`: additional artifact tag. Can be repeated multiple time\n* `--type`: type of artifact to be pushed. Allowed values: `rulesfile`, `plugin`, `asset`\n* `--version`: (**required**) artifact version in semver format (e.g., `1.0.0`, `0.1.2-rc1`). See [Artifact References and Versions](#artifact-references-and-versions) for details.\n\n### Falcoctl registry pull\nPulling **artifacts** involves specifying the reference. The type of **artifact** is not required since the tool will implicitly extract it from the OCI **artifact**:\n```\n$ falcoctl registry pull ghcr.io/falcosecurity/plugins/plugin/cloudtrail:0.3.0\n```\n\n# Falcoctl Environment Variables\n\nThe arguments of `falcoctl` can passed as arguments through:\n - command line options\n - environment variables\n - configuration file\n\nThe `falcoctl` arguments can be passed through these different modalities are prioritized in the following order: command line options, environment variables, and finally the configuration file. This means that if an argument is passed through multiple modalities, the value set in the command line options will take precedence over the value set in environment variables, which will in turn take precedence over the value set in the configuration file.\n\nThis is the list of the environment variable that `falcoctl` will use:\n\n| Name                                      | Content                                                          |\n| ----------------------------------------- | ---------------------------------------------------------------- |\n| `FALCOCTL_REGISTRY_AUTH_BASIC`            | `registry,username,password;registry1,username1,password1`       |\n| `FALCOCTL_REGISTRY_AUTH_OAUTH`            | `registry,client-id,client-secret,token-url;registry1`           |\n| `FALCOCTL_REGISTRY_AUTH_GCP`              | `registry;registry1`                                             |\n| `FALCOCTL_INDEXES`                        | `index-name,https://falcosecurity.github.io/falcoctl/index.yaml` |\n| `FALCOCTL_ARTIFACT_FOLLOW_EVERY`          | `6h0m0s`                                                         |\n| `FALCOCTL_ARTIFACT_FOLLOW_CRON`           | `cron-formatted-string`                                          |\n| `FALCOCTL_ARTIFACT_FOLLOW_REFS`           | `ref1;ref2`                                                      |\n| `FALCOCTL_ARTIFACT_FOLLOW_FALCOVERSIONS`  | `falco-version-url`                                              |\n| `FALCOCTL_ARTIFACT_FOLLOW_RULESFILEDIR`   | `rules-directory-path`                                           |\n| `FALCOCTL_ARTIFACT_FOLLOW_PLUGINSDIR`     | `plugins-directory-path`                                         |\n| `FALCOCTL_ARTIFACT_FOLLOW_STATEDIR`       | `state-directory-path`                                           |\n| `FALCOCTL_ARTIFACT_FOLLOW_TMPDIR`         | `tmp-directory-path`                                             |\n| `FALCOCTL_ARTIFACT_INSTALL_REFS`          | `ref1;ref2`                                                      |\n| `FALCOCTL_ARTIFACT_INSTALL_RULESFILESDIR` | `rules-directory-path`                                           |\n| `FALCOCTL_ARTIFACT_INSTALL_PLUGINSDIR`    | `plugins-directory-path`                                         |\n| `FALCOCTL_ARTIFACT_INSTALL_STATEDIR`      | `state-directory-path`                                           |\n| `FALCOCTL_ARTIFACT_NOVERIFY`              |                                                                  | \n\nPlease note that when passing multiple arguments via an environment variable, they must be separated by a semicolon. Moreover, multiple fields of the same argument must be separated by a comma.\n\nHere is an example of `falcoctl` usage with environment variables:\n\n```bash\n$ export FALCOCTL_REGISTRY_AUTH_OAUTH=\"localhost:6000,000000,999999,http://localhost:9096/token\"\n$ falcoctl registry oauth \n```\n\n# Container image signature verification\n\nOfficial container images for Falcoctl, starting from version 0.5.0, are signed with [cosign](https://github.com/sigstore/cosign) v2. To verify the signature run:\n\n```bash\n$ FALCOCTL_VERSION=x.y.z # e.g. 0.5.0\n$ cosign verify docker.io/falcosecurity/falcoctl:$FALCOCTL_VERSION --certificate-oidc-issuer=https://token.actions.githubusercontent.com --certificate-identity-regexp=https://github.com/falcosecurity/falcoctl/ --certificate-github-workflow-ref=refs/tags/v$FALCOCTL_VERSION\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffalcosecurity%2Ffalcoctl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffalcosecurity%2Ffalcoctl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffalcosecurity%2Ffalcoctl/lists"}