mirror of
https://github.com/larksuite/cli.git
synced 2026-07-08 02:00:19 +08:00
136 lines
3.9 KiB
Markdown
136 lines
3.9 KiB
Markdown
# secplugin Usage Guide
|
|
|
|
Chinese version: see `README.zh-CN.md`.
|
|
|
|
`secplugin` enables a secure proxy mode for the CLI. It forces outbound HTTP(S)
|
|
requests to go through a local security proxy and can optionally trust an
|
|
additional CA certificate bundle.
|
|
|
|
It supports two configuration methods:
|
|
|
|
1. `sec_config.json`
|
|
2. `LARKSUITE_CLI_SEC_*` environment variables
|
|
|
|
## Config File Location
|
|
|
|
Default config file path:
|
|
|
|
```text
|
|
~/.lark-cli/sec_config.json
|
|
```
|
|
|
|
If `LARKSUITE_CLI_CONFIG_DIR` is set, the path becomes:
|
|
|
|
```text
|
|
$LARKSUITE_CLI_CONFIG_DIR/sec_config.json
|
|
```
|
|
|
|
## Option 1: Config File
|
|
|
|
Put the following content into `sec_config.json`:
|
|
|
|
```json
|
|
{
|
|
"LARKSUITE_CLI_SEC_ENABLE": true,
|
|
"LARKSUITE_CLI_SEC_PROXY": "http://127.0.0.1:3128",
|
|
"LARKSUITE_CLI_SEC_CA": "/absolute/path/to/proxy-ca.pem",
|
|
"LARKSUITE_CLI_SEC_AUTH": true,
|
|
"LARKSUITE_CLI_APP_ID": "cli_xxx",
|
|
"LARKSUITE_CLI_BRAND": "feishu",
|
|
"LARKSUITE_CLI_DEFAULT_AS": "bot",
|
|
"LARKSUITE_CLI_STRICT_MODE": "bot"
|
|
}
|
|
```
|
|
|
|
Field descriptions:
|
|
|
|
- `LARKSUITE_CLI_SEC_ENABLE`: Enables secplugin. Boolean values are supported.
|
|
- `LARKSUITE_CLI_SEC_PROXY`: Local HTTP proxy address. It must be `http://127.0.0.1:<port>`.
|
|
- `LARKSUITE_CLI_SEC_CA`: Absolute path to an extra trusted root CA PEM file. Leave empty if not needed.
|
|
- `LARKSUITE_CLI_SEC_AUTH`: Enables proxy-injected token mode.
|
|
- `LARKSUITE_CLI_APP_ID`: Optional app ID used in `SEC_AUTH` mode.
|
|
- `LARKSUITE_CLI_BRAND`: Optional, must be `feishu` or `lark`.
|
|
- `LARKSUITE_CLI_DEFAULT_AS`: Optional, must be `user`, `bot`, or `auto`.
|
|
- `LARKSUITE_CLI_STRICT_MODE`: Optional, must be `user`, `bot`, or `off`.
|
|
|
|
## Option 2: Environment Variables
|
|
|
|
You can also enable secplugin directly with environment variables without
|
|
creating `sec_config.json`:
|
|
|
|
```bash
|
|
export LARKSUITE_CLI_SEC_ENABLE=true
|
|
export LARKSUITE_CLI_SEC_PROXY=http://127.0.0.1:3128
|
|
export LARKSUITE_CLI_SEC_CA=/absolute/path/to/proxy-ca.pem
|
|
export LARKSUITE_CLI_SEC_AUTH=true
|
|
```
|
|
|
|
If you want to provide app metadata in `SEC_AUTH` mode, set these as well:
|
|
|
|
```bash
|
|
export LARKSUITE_CLI_APP_ID=cli_xxx
|
|
export LARKSUITE_CLI_BRAND=feishu
|
|
export LARKSUITE_CLI_DEFAULT_AS=bot
|
|
export LARKSUITE_CLI_STRICT_MODE=bot
|
|
```
|
|
|
|
## Precedence
|
|
|
|
The following environment variables override the corresponding fields in
|
|
`sec_config.json` when they are present:
|
|
|
|
- `LARKSUITE_CLI_SEC_ENABLE`
|
|
- `LARKSUITE_CLI_SEC_PROXY`
|
|
- `LARKSUITE_CLI_SEC_CA`
|
|
- `LARKSUITE_CLI_SEC_AUTH`
|
|
- `LARKSUITE_CLI_APP_ID`
|
|
- `LARKSUITE_CLI_BRAND`
|
|
- `LARKSUITE_CLI_DEFAULT_AS`
|
|
- `LARKSUITE_CLI_STRICT_MODE`
|
|
|
|
This means:
|
|
|
|
- Put stable defaults in `sec_config.json`.
|
|
- Use environment variables for temporary overrides.
|
|
- SEC-related environment variables can work even without a config file.
|
|
|
|
## SEC_AUTH Mode
|
|
|
|
The CLI enters `SEC_AUTH` mode when both of the following are true:
|
|
|
|
```text
|
|
LARKSUITE_CLI_SEC_ENABLE=true
|
|
LARKSUITE_CLI_SEC_AUTH=true
|
|
```
|
|
|
|
In this mode, the CLI does not read real tokens directly. Instead, it returns
|
|
placeholder tokens and expects the proxy to replace them with real credentials.
|
|
|
|
App information is resolved in this order:
|
|
|
|
1. `LARKSUITE_CLI_APP_ID` and `LARKSUITE_CLI_BRAND` from environment variables
|
|
2. The same fields in `sec_config.json`
|
|
3. The active profile in the regular CLI `config.json`
|
|
|
|
If no valid app information can be resolved from any source, the command fails.
|
|
|
|
## Constraints
|
|
|
|
- `LARKSUITE_CLI_SEC_PROXY` must use the `http` scheme only.
|
|
- The host of `LARKSUITE_CLI_SEC_PROXY` must be `127.0.0.1`.
|
|
- `LARKSUITE_CLI_SEC_PROXY` must not contain a path.
|
|
- `LARKSUITE_CLI_SEC_CA` must be an absolute path to a PEM file.
|
|
- Boolean values support `true/false`, `1/0`, `on/off`, `yes/no`, and `y/n`.
|
|
|
|
## Recommendations
|
|
|
|
For long-term stable setup, prefer `sec_config.json`:
|
|
|
|
- Good for developer machines or controlled environments.
|
|
- Avoids repeatedly injecting environment variables into the shell.
|
|
|
|
For temporary debugging, prefer environment variables:
|
|
|
|
- Good for switching proxy or CA for just one session.
|
|
- No need to modify files on disk.
|