diff --git a/docs/deployment/integration-manager.md b/docs/deployment/integration-manager.md index 56ad907e..584a21af 100644 --- a/docs/deployment/integration-manager.md +++ b/docs/deployment/integration-manager.md @@ -11,6 +11,8 @@ The OpenCTI Integration Manager is a deployment tool that simplifies the managem - [Quick start](integration-manager/quick-start.md) - Get up and running quickly - [Architecture design](integration-manager/architecture.md) - Detailed technical architecure documentation + - [Private Registry Authentication](integration-manager/registry-authentification.md) - Configure private Docker registries and authentication handling + - [Proxy Support](integration-manager/proxy-configuration.md) - Configure system proxy and HTTPS proxy certificates - [Installation guide](integration-manager/installation.md) - System requirements and installation methods - [Configuration reference](integration-manager/configuration.md) - Complete configuration documentation - [Security deep dive](integration-manager/security.md) - Database, encryption, and access control documentation diff --git a/docs/deployment/integration-manager/configuration.md b/docs/deployment/integration-manager/configuration.md index be819e28..d0cdd153 100644 --- a/docs/deployment/integration-manager/configuration.md +++ b/docs/deployment/integration-manager/configuration.md @@ -58,6 +58,38 @@ Example: `manager.logger.level` becomes `MANAGER__LOGGER__LEVEL` | opencti:with_proxy | OPENCTI__WITH_PROXY | `false` | Use system proxy settings for connection | | opencti:logs_schedule | OPENCTI__LOGS_SCHEDULE | 10 | Maximum interval in seconds between log reports | +#### Proxy configuration + +| Parameter | Environment variable | Default value | Description | +|:----------------------------------|:---------------------------------|:--------------|:--------------------------------------------------------------------------------------------------| +| http_proxy | HTTP_PROXY | | Proxy URL for HTTP requests (e.g., `http://proxy:8080`) | +| https_proxy | HTTPS_PROXY | | Proxy URL for HTTPS requests (e.g., `http://proxy:8080`) | +| no_proxy | NO_PROXY | | Comma-separated list of hosts excluded from proxy (e.g., `localhost,127.0.0.1,internal.domain`) | +| https_proxy_ca | HTTPS_PROXY_CA | | CA certificates used to validate HTTPS proxy connections | +| https_proxy_reject_unauthorized | HTTPS_PROXY_REJECT_UNAUTHORIZED | `false` | If not false, validates the proxy certificate against the provided CA list | + +!!! note "Proxy certificate separation" + + Proxy TLS certificates are **independent** from OpenCTI HTTPS server certificates. + + - For proxy connections → use `https_proxy_ca` and `https_proxy_reject_unauthorized` + - For OpenCTI platform HTTPS → use `app:https_cert:*` variables in the main OpenCTI configuration + +### Registry authentication + +| Parameter | Environment variable | Default value | Description | +|:------------------------------|:------------------------------|:--------------|:----------------------------------------------------------------------------| +| registry:enable | REGISTRY__ENABLE | `false` | Enable authentication to a container registry | +| registry:url | REGISTRY__URL | | Registry endpoint (e.g., `https://registry.hub.docker.com`) | +| registry:username | REGISTRY__USERNAME | | Username for registry authentication | +| registry:password | REGISTRY__PASSWORD | | Password or token for registry authentication | +| registry:cache_ttl | REGISTRY__CACHE_TTL | 3600 | Time (in seconds) for caching registry authorization tokens | + +!!! note "Authentication cache" + + Composer caches registry authentication tokens to reduce the number of login requests. + Tokens are refreshed automatically when expired. + #### OpenBAS (Coming Soon) !!! note "OpenBAS Integration" diff --git a/docs/deployment/integration-manager/proxy-configuration.md b/docs/deployment/integration-manager/proxy-configuration.md new file mode 100644 index 00000000..b438defe --- /dev/null +++ b/docs/deployment/integration-manager/proxy-configuration.md @@ -0,0 +1,69 @@ +# Proxy Support + +## Overview + +XTM Composer can use system proxy settings for outgoing network calls. + +### YAML configuration + +```yaml +opencti: + daemon: + with_proxy: true +``` + +### Environment variable configuration + +```bash +export OPENCTI__DAEMON__WITH_PROXY="true" +export HTTP_PROXY="http://proxy.example.com:8080" +export HTTPS_PROXY="http://proxy.example.com:8080" +export NO_PROXY="localhost,127.0.0.1,.example.com" +``` + +When enabled, the Integration Manager automatically applies the proxy settings to: + +- Docker API calls +- Kubernetes image pulls +- Portainer API requests + +## HTTPS Proxy Certificate Support (optional) + +Some environments use HTTPS proxies with TLS interception (for example, corporate proxies or debugging proxies like Burp). +In these cases, additional certificate settings may be required. + +### Environment variables + +```bash +export HTTPS_PROXY_CA='["/path/to/proxy-ca.pem"]' +export HTTPS_PROXY_REJECT_UNAUTHORIZED="false" +``` +- HTTPS_PROXY_CA — List of CA certificates (file paths or PEM blocks) used to validate the proxy’s certificate. +- HTTPS_PROXY_REJECT_UNAUTHORIZED — If set to "false", certificate validation is disabled for proxy connections (default behavior). + +### Important: Certificate Scope Clarification + +Composer distinguishes two independent certificate configurations: + +| Purpose | Keys | Description | +|-----------------------------------|-------------------------------------------------------|------------------------------------------------------------------| +| OpenCTI HTTPS server certificates | app.https_cert.ca, app.https_cert.reject_unauthorized | TLS configuration for the OpenCTI web server | +| Proxy HTTPS certificates | https_proxy_ca, https_proxy_reject_unauthorized | Validation settings for HTTPS connections made through the proxy | + +These settings must not be mixed. + +### Proxy Configuration in config.json + +Example of equivalent configuration in a JSON file: + +```json +{ + "http_proxy": "http://proxy.example.com:8080", + "https_proxy": "http://proxy.example.com:8080", + "no_proxy": "localhost,127.0.0.1,internal.domain", + "https_proxy_ca": ["/path/to/proxy-ca.pem"], + "https_proxy_reject_unauthorized": false +} +``` + +See also: [Private Registry Authentication](registry-authentification.md) \ No newline at end of file diff --git a/docs/deployment/integration-manager/registry-authentification.md b/docs/deployment/integration-manager/registry-authentification.md new file mode 100644 index 00000000..23318904 --- /dev/null +++ b/docs/deployment/integration-manager/registry-authentification.md @@ -0,0 +1,67 @@ +# Private Registry + +## Overview + +XTM Composer supports the deployment of containers from both public and private Docker registries. +Registry authentication is configured through the OpenCTI daemon settings and automatically applied by the Integration Manager during connector deployment. + +This page explains how to configure: + +- Private Docker registry authentication +- Registry prefix resolution + +--- + +## Private Docker Registry + +The Integration Manager automatically uses the registry configuration defined under `opencti.daemon.registry`. +No additional configuration is required inside Composer. + +```yaml +opencti: + daemon: + registry: + server: "registry.example.com" + username: "myuser" + password: "mypassword" + email: "user@example.com" + token_ttl: 1800 # Optional, default 30 minutes + retry_attempts: 3 # Optional + retry_delay: 5 # Optional (seconds) +``` + +## Environment variable configuration + +To configure your private registry using environment variables, export: + +```bash +export OPENCTI__DAEMON__REGISTRY__SERVER="custom.registry.io" +export OPENCTI__DAEMON__REGISTRY__USERNAME="myuser" +export OPENCTI__DAEMON__REGISTRY__PASSWORD="mypassword" +export OPENCTI__DAEMON__REGISTRY__EMAIL="user@company.com" +export OPENCTI__DAEMON__REGISTRY__TOKEN_TTL="1800" +export OPENCTI__DAEMON__REGISTRY__RETRY_ATTEMPTS="3" +export OPENCTI__DAEMON__REGISTRY__RETRY_DELAY="5" +``` + +If no registry configuration is provided, the Integration Manager assumes that images are publicly accessible. + +## Registry Prefix Resolution + +The Integration Manager automatically handles registry prefixes in image names: + +- If the image name already includes the registry, it will not prepend anything. +- If no registry is included, the `server` from the registry configuration is automatically prefixed. +- This prevents double-prefixing and ensures images are pulled from the correct registry. + +Example: + +```yaml +# Image without prefix +image: "opencti/connector-example:1.0.0" + +# After resolution +image: "registry.example.com/opencti/connector-example:1.0.0" +``` + +See also: [Proxy Support](proxy-configuration.md) \ No newline at end of file