Keychain cache and throttling documentation. (osquery#8205)

trailofbits · Dec 18, 2023 · f1af50c · f1af50c
1 parent e042cea
commit f1af50c
Showing 1 changed file with 18 additions and 0 deletions.
diff --git a/docs/wiki/installation/cli-flags.md b/docs/wiki/installation/cli-flags.md
@@ -690,3 +690,21 @@ otherwise its fallback mechanism will be used.
 
 Configure the region to use for the AWS Kinesis logger plugin. If not specified, the `--aws_region` flag value will be used if set,
 otherwise its fallback mechanism will be used.
+
+## macOS keychain flags
+
+By default, Osquery limits frequent access to keychain files on macOS. This limit applies to `certificates`, `keychain_acls`, and `keychain_items` tables.
+
+`--keychain_access_cache=true`
+
+Whether to use a cache for keychain access (default true). The cache resides in-memory, and independent entries are used for each table and keychain file.
+If the keychain file has NOT been modified, osquery will return the cached result. The cache does not expire. It is cleared when osquery is restarted.
+
+`--keychain_access_interval=5`
+
+Minimum minutes required between keychain accesses (default is 5). Keychain cache must be enabled.
+The access interval is the minimum time that must elapse before osquery will open and read a keychain file.
+Starting from the first access and until time + `--keychain_access_interval`, osquery will return cached results for a given keychain file.
+The interval is applied independently for each table. Therefore, multiple tables can read the same keychain file, but they can only do so once within the interval.
+Since keychain files are generally not updated frequently, we expect that most keychain accesses will not be impacted by this interval.
+To disable the keychain access interval: `--keychain_access_interval=0`