Skip to content

Commit 3eb3e9e

Browse files
committed
Update configuration
1 parent be67047 commit 3eb3e9e

File tree

11 files changed

+732
-269
lines changed

11 files changed

+732
-269
lines changed

content/configuration/_index.md

Lines changed: 487 additions & 74 deletions
Large diffs are not rendered by default.

content/usage/osctrl-admin/_index.md

Lines changed: 66 additions & 62 deletions
Large diffs are not rendered by default.

content/usage/osctrl-api/_index.md

Lines changed: 55 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -15,51 +15,67 @@ NAME:
1515
osctrl-api - API service for osctrl, a fast and efficient osquery management
1616

1717
USAGE:
18-
osctrl-api [global options] command [command options] [arguments...]
19-
20-
VERSION:
21-
0.4.1
18+
osctrl-api [global options] [command [command options]]
2219

2320
DESCRIPTION:
2421
API service for osctrl, a fast and efficient osquery management
2522

2623
COMMANDS:
2724
help
25+
config-validate, config-verify Validate YAML configuration file
26+
config-generate Generate an example configuration file using the current flag values
2827

2928
GLOBAL OPTIONS:
30-
--config, -c Provide service configuration via JSON file (default: false) [$SERVICE_CONFIG]
31-
--config-file FILE, -C FILE Load service configuration from FILE (default: "config/api.json") [$SERVICE_CONFIG_FILE]
32-
--listener value, -l value Listener for the service (default: "0.0.0.0") [$SERVICE_LISTENER]
33-
--port value, -p value TCP port for the service (default: "9002") [$SERVICE_PORT]
34-
--auth value, -A value Authentication mechanism for the service (default: "none") [$SERVICE_AUTH]
35-
--host value, -H value Exposed hostname the service uses (default: "0.0.0.0") [$SERVICE_HOST]
36-
--logging value, -L value Logging mechanism to handle logs from nodes (default: "none") [$SERVICE_LOGGER]
37-
--redis, -r Provide redis configuration via JSON file (default: false) [$REDIS_CONFIG]
38-
--redis-file FILE, -R FILE Load redis configuration from FILE (default: "config/redis.json") [$REDIS_CONFIG_FILE]
39-
--redis-connection-string value Redis connection string, must include schema (<redis|rediss|unix>://<user>:<pass>@<host>:<port>/<db>?<options> [$REDIS_CONNECTION_STRING]
40-
--redis-host value Redis host to be connected to (default: "127.0.0.1") [$REDIS_HOST]
41-
--redis-port value Redis port to be connected to (default: "6379") [$REDIS_PORT]
42-
--redis-pass value Password to be used for redis [$REDIS_PASS]
43-
--redis-db value Redis database to be selected after connecting (default: 0) [$REDIS_DB]
44-
--redis-conn-retry value Time in seconds to retry the connection to the cache, if set to 0 the service will stop if the connection fails (default: 7) [$REDIS_CONN_RETRY]
45-
--db, -d Provide DB configuration via JSON file (default: false) [$DB_CONFIG]
46-
--db-file FILE, -D FILE Load DB configuration from FILE (default: "config/db.json") [$DB_CONFIG_FILE]
47-
--db-host value Backend host to be connected to (default: "127.0.0.1") [$DB_HOST]
48-
--db-port value Backend port to be connected to (default: "5432") [$DB_PORT]
49-
--db-name value Database name to be used in the backend (default: "osctrl") [$DB_NAME]
50-
--db-user value Username to be used for the backend (default: "postgres") [$DB_USER]
51-
--db-pass value Password to be used for the backend (default: "postgres") [$DB_PASS]
52-
--db-sslmode value SSL native support to encrypt the connection to the backend (default: "disable") [$DB_SSLMODE]
53-
--db-max-idle-conns value Maximum number of connections in the idle connection pool (default: 20) [$DB_MAX_IDLE_CONNS]
54-
--db-max-open-conns value Maximum number of open connections to the database (default: 100) [$DB_MAX_OPEN_CONNS]
55-
--db-conn-max-lifetime value Maximum amount of time a connection may be reused (default: 30) [$DB_CONN_MAX_LIFETIME]
56-
--db-conn-retry value Time in seconds to retry the connection to the database, if set to 0 the service will stop if the connection fails (default: 7) [$DB_CONN_RETRY]
57-
--tls, -t Enable TLS termination. It requires certificate and key (default: false) [$TLS_SERVER]
58-
--cert FILE, -T FILE TLS termination certificate from FILE (default: "config/tls.crt") [$TLS_CERTIFICATE]
59-
--key FILE, -K FILE TLS termination private key from FILE (default: "config/tls.key") [$TLS_KEY]
60-
--jwt, -j Provide JWT configuration via JSON file (default: false) [$JWT_CONFIG]
61-
--jwt-file FILE Load JWT configuration from FILE (default: "config/jwt.json") [$JWT_CONFIG_FILE]
62-
--jwt-secret value Password to be used for the backend [$JWT_SECRET]
63-
--jwt-expire value Maximum amount of hours for the tokens to expire (default: 3) [$JWT_EXPIRE]
64-
--version, -v print the version
29+
--config, -c Provide service configuration via YAML file [$SERVICE_CONFIG]
30+
--config-file FILE, -C FILE Load service configuration from FILE (default: "./config/api.yml") [$SERVICE_CONFIG_FILE]
31+
--listener string, -l string Listener for the service (default: "127.0.0.1") [$SERVICE_LISTENER]
32+
--port int, -p int TCP port for the service (default: 9000) [$SERVICE_PORT]
33+
--host string, -H string Exposed hostname the service uses (default: "osctrl.net") [$SERVICE_HOST]
34+
--auth string, -A string Authentication mechanism for the service (default: "none") [$SERVICE_AUTH]
35+
--log-level string Log level for the service (default: "info") [$SERVICE_LOG_LEVEL]
36+
--log-format string Log format for the service (default: "json") [$SERVICE_LOG_FORMAT]
37+
--audit-log, --audit Enable audit log for the service. Logs all sensitive actions [$AUDIT_LOG]
38+
--logger string, -L string Logger mechanism to handle status/result logs from nodes (default: "db") [$SERVICE_LOGGER]
39+
--logger-db-same Use the same DB configuration for the logger [$LOGGER_DB_SAME]
40+
--always-log, -a, --always Always log status and on-demand query logs from nodes in database [$ALWAYS_LOG]
41+
--redis-connection-string string Redis connection string, must include schema (<redis|rediss|unix>://<user>:<pass>@<host>:<port>/<db>?<options> [$REDIS_CONNECTION_STRING]
42+
--redis-host string Redis host to be connected to (default: "127.0.0.1") [$REDIS_HOST]
43+
--redis-port int Redis port to be connected to (default: 6379) [$REDIS_PORT]
44+
--redis-pass string Password to be used for redis [$REDIS_PASS]
45+
--redis-db int Redis database to be selected after connecting (default: 0) [$REDIS_DB]
46+
--redis-conn-retry int Time in seconds to retry the connection to the cache, if set to 0 the service will stop if the connection fails (default: 10) [$REDIS_CONN_RETRY]
47+
--db-type string Type of backend to be used (default: "postgres") [$DB_TYPE]
48+
--db-host string Backend host to be connected to (default: "127.0.0.1") [$DB_HOST]
49+
--db-port int Backend port to be connected to (default: 5432) [$DB_PORT]
50+
--db-name string Database name to be used in the backend (default: "osctrl") [$DB_NAME]
51+
--db-user string Username to be used for the backend (default: "postgres") [$DB_USER]
52+
--db-pass string Password to be used for the backend (default: "postgres") [$DB_PASS]
53+
--db-sslmode string SSL native support to encrypt the connection to the backend (default: "disable") [$DB_SSLMODE]
54+
--db-max-idle-conns int Maximum number of connections in the idle connection pool (default: 20) [$DB_MAX_IDLE_CONNS]
55+
--db-max-open-conns int Maximum number of open connections to the database (default: 100) [$DB_MAX_OPEN_CONNS]
56+
--db-conn-max-lifetime int Maximum amount of time a connection may be reused (default: 30) [$DB_CONN_MAX_LIFETIME]
57+
--db-conn-retry int Time in seconds to retry the connection to the database, if set to 0 the service will stop if the connection fails (default: 10) [$DB_CONN_RETRY]
58+
--db-filepath string File path to the SQLite database, only used when type is sqlite (default: "./osctrl.db") [$DB_SQLITE_FILEPATH]
59+
--tls, -t Enable TLS termination. It requires certificate and key [$TLS_SERVER]
60+
--cert FILE, -T FILE TLS termination certificate from FILE (default: "./config/tls.crt") [$TLS_CERTIFICATE]
61+
--key FILE, -K FILE TLS termination private key from FILE (default: "./config/tls.key") [$TLS_KEY]
62+
--jwt-secret string Password to be used for the backend [$JWT_SECRET]
63+
--jwt-expire int Maximum amount of hours for the tokens to expire (default: 3) [$JWT_EXPIRE]
64+
--osquery-version string Version of osquery to be used (default: "5.20.0") [$OSQUERY_VERSION]
65+
--osquery-tables-file string File with the osquery tables to be used (default: "./data/5.20.0.json") [$OSQUERY_TABLES]
66+
--osquery-logger Enable remote tls logger for osquery [$OSQUERY_LOGGER]
67+
--osquery-config Enable remote tls config for osquery [$OSQUERY_CONFIG]
68+
--osquery-query Enable remote tls queries for osquery [$OSQUERY_QUERY]
69+
--osquery-carve Enable remote tls carver for osquery [$OSQUERY_CARVE]
70+
--carver-type string Carver to be used to receive files extracted from nodes (default: "db") [$CARVER_TYPE]
71+
--carver-s3-bucket string S3 bucket to be used as configuration for carves [$CARVER_S3_BUCKET]
72+
--carver-s3-region string S3 region to be used as configuration for carves [$CARVER_S3_REGION]
73+
--carve-s3-key-id string S3 access key id to be used as configuration for carves [$CARVER_S3_KEY_ID]
74+
--carve-s3-secret string S3 access key secret to be used as configuration for carves [$CARVER_S3_SECRET]
75+
--carver-local-dir string Local directory to store carved files (default: "./carved_files/") [$CARVER_LOCAL_DIR]
76+
--enable-http-debug Enable HTTP Debug mode to dump full HTTP incoming request [$HTTP_DEBUG]
77+
--http-debug-file string File to dump the HTTP requests when HTTP Debug mode is enabled (default: "./debug-http-api.log") [$HTTP_DEBUG_FILE]
78+
--http-debug-show-body Show body of the HTTP requests when HTTP Debug mode is enabled [$HTTP_DEBUG_SHOW_BODY]
79+
--version, -v Print version information
80+
--help, -h show help
6581
```

content/usage/osctrl-cli/_index.md

Lines changed: 29 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -10,53 +10,51 @@ pre = ""
1010
Execute `./osctrl-cli help` to show the main help of the program:
1111

1212
```properties
13-
$ ./bin/osctrl-cli help
13+
$ ./osctrl-cli help
1414
NAME:
1515
osctrl-cli - CLI for osctrl
1616

1717
USAGE:
18-
osctrl-cli [global options] command [command options]
19-
20-
VERSION:
21-
0.4.6
18+
osctrl-cli [global options] [command [command options]]
2219

2320
DESCRIPTION:
2421
CLI for osctrl, a fast and efficient osquery management
2522

2623
COMMANDS:
27-
user Commands for users
24+
audit-logs Get all audit logs for actions performed in osctrl
25+
carve Commands for file carves
26+
check-api Checks API token
27+
check-db Checks DB connection
2828
environment, env Commands for TLS environment
29-
settings Commands for settings
29+
login Login into API and generate JSON config file with token
3030
node Commands for nodes
3131
query Commands for queries
32-
carve Commands for file carves
32+
settings Commands for settings
3333
tag Commands for tags
34-
check-db Checks DB connection
35-
check-api Checks API token
36-
login Login into API and generate JSON config file with token
34+
user Commands for users
3735
help, h Shows a list of commands or help for one command
3836

3937
GLOBAL OPTIONS:
40-
--db, -d Connect to local osctrl DB using JSON config file (default: false) [$DB_CONFIG]
41-
--api, -a Connect to remote osctrl using JSON config file (default: true) [$API_CONFIG]
42-
--api-file FILE, -A FILE Load API JSON configuration from FILE (default: "osctrl-api.json") [$API_CONFIG_FILE]
43-
--api-url value, -U value The URL for osctrl API to be used [$API_URL]
44-
--api-token value, -T value Token to authenticate with the osctrl API [$API_TOKEN]
45-
--db-file FILE, -D FILE Load DB JSON configuration from FILE [$DB_CONFIG_FILE]
46-
--db-host value Backend host to be connected to (default: "127.0.0.1") [$DB_HOST]
47-
--db-port value Backend port to be connected to (default: "5432") [$DB_PORT]
48-
--db-name value Database name to be used in the backend (default: "osctrl") [$DB_NAME]
49-
--db-user value Username to be used for the backend (default: "postgres") [$DB_USER]
50-
--db-pass value Password to be used for the backend (default: "postgres") [$DB_PASS]
51-
--db-max-idle-conns value Maximum number of connections in the idle connection pool (default: 20) [$DB_MAX_IDLE_CONNS]
52-
--db-max-open-conns value Maximum number of open connections to the database (default: 100) [$DB_MAX_OPEN_CONNS]
53-
--db-conn-max-lifetime value Maximum amount of time a connection may be reused (default: 30) [$DB_CONN_MAX_LIFETIME]
54-
--insecure, -i Allow insecure server connections when using SSL (default: false)
55-
--verbose, -V Increase output verbosity for debugging (default: false)
56-
--output-format value, -o value Format to be used for data output (default: "pretty") [$OUTPUT_FORMAT]
57-
--silent, -s Silent mode (default: false)
58-
--help, -h Show help (default: false)
59-
--version, -v Print version information (default: false)
38+
--db, -d Connect to local osctrl DB using YAML config file [$DB_CONFIG]
39+
--api, -a Connect to remote osctrl using JSON config file [$API_CONFIG]
40+
--api-file FILE, -A FILE Load API JSON configuration from FILE (default: "osctrl-api.json") [$API_CONFIG_FILE]
41+
--api-url string, -U string The URL for osctrl API to be used [$API_URL]
42+
--api-token string, -T string Token to authenticate with the osctrl API [$API_TOKEN]
43+
--db-file FILE, -D FILE Load DB YAML configuration from FILE [$DB_CONFIG_FILE]
44+
--db-host string Backend host to be connected to (default: "127.0.0.1") [$DB_HOST]
45+
--db-port int Backend port to be connected to (default: 5432) [$DB_PORT]
46+
--db-name string Database name to be used in the backend (default: "osctrl") [$DB_NAME]
47+
--db-user string Username to be used for the backend (default: "postgres") [$DB_USER]
48+
--db-pass string Password to be used for the backend (default: "postgres") [$DB_PASS]
49+
--db-max-idle-conns int Maximum number of connections in the idle connection pool (default: 20) [$DB_MAX_IDLE_CONNS]
50+
--db-max-open-conns int Maximum number of open connections to the database (default: 100) [$DB_MAX_OPEN_CONNS]
51+
--db-conn-max-lifetime int Maximum amount of time a connection may be reused (default: 30) [$DB_CONN_MAX_LIFETIME]
52+
--insecure, -i Allow insecure server connections when using SSL
53+
--verbose, -V Increase output verbosity for debugging
54+
--output-format string, -o string Format to be used for data output (default: "pretty") [$OUTPUT_FORMAT]
55+
--silent, -s Silent mode
56+
--version, -v Print version information
57+
--help, -h show help
6058
```
6159

6260
Each command has its own help and it is displayed appending `-h` to them. Each subcommand has its own help as well.
Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
+++
2+
title = "audit-logs"
3+
date = 2025-12-27T15:21:37+01:00
4+
weight = 7
5+
pre = ""
6+
+++
7+
8+
### Audit Logs
9+
10+
```properties
11+
$ ./bin/osctrl-cli audit-logs -h
12+
NAME:
13+
osctrl-cli audit-logs - Get all audit logs for actions performed in osctrl
14+
15+
USAGE:
16+
osctrl-cli audit-logs [command options]
17+
18+
OPTIONS:
19+
--help, -h Show help (default: false)
20+
```
21+
22+
This command retrieves all audit logs for actions performed in **osctrl**.

content/usage/osctrl-cli/check-api/_index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ weight = 7
55
pre = ""
66
+++
77

8-
### Check
8+
### Check API
99

1010
```properties
1111
$ ./bin/osctrl-cli check-api -h

content/usage/osctrl-cli/check-db/_index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ weight = 6
55
pre = ""
66
+++
77

8-
### Check
8+
### Check DB
99

1010
```properties
1111
$ ./osctrl-cli check-db -h

0 commit comments

Comments
 (0)