# AI Assistant

> AI security assistant in SecureBaseline Cloud - diagnose CIS findings and get remediation advice via YandexGPT, OpenAI, Anthropic, AWS Bedrock, or Vertex AI

Source: https://opennix.org/en/docs/haas/ai-assistant/

## Overview

The AI Assistant uses LLM providers to provide intelligent help with CIS benchmarks, compliance scanning, and hardening troubleshooting. SecureBaseline Cloud supports 7 providers out of the box and any OpenAI-compatible endpoint.

## Supported Providers

| Provider | Protocol | Authentication | Use Case |
|----------|----------|----------------|----------|
| YandexGPT | OpenAI-compatible | API Key or IAM Token + Folder ID | Yandex Cloud deployments |
| OpenAI | OpenAI API | API Key | GPT-4o, GPT-4-turbo |
| Azure OpenAI | OpenAI-compatible | API Key + Endpoint URL | Enterprise Azure deployments |
| Anthropic | Messages API | API Key | Claude Sonnet, Opus |
| AWS Bedrock | Converse API (SigV4) | ACCESS_KEY_ID:SECRET_ACCESS_KEY or IAM Role | AWS deployments |
| Google Vertex AI | Express Mode or Full Mode | API Key (Express) or OAuth2 (Full) | GCP deployments, Gemini |
| Custom | OpenAI-compatible | API Key (optional) | Ollama, Mistral, vLLM, LiteLLM |

## Navigation

**Menu**: AI Tools > LLM Settings

## Page Layout

The LLM Settings page has two tabs:

### Configs Tab

Manage LLM configurations.

| Control | Description |
|---------|-------------|
| Add Config | Create a new LLM configuration |
| Configs Table | List of all configurations with inline actions |

### Usage Tab

View usage statistics:
- **Total Requests** - number of AI API calls
- **Input Tokens** - total tokens sent to AI
- **Output Tokens** - total tokens received from AI
- **Per-Provider Breakdown** - table showing requests and tokens per provider/model

## Configuration Management

### Configs Table Columns

| Column | Description |
|--------|-------------|
| Name | Configuration name with Default tag if applicable |
| Provider | LLM provider tag (color-coded) |
| Model | Model name |
| Default Config | Toggle switch to set/unset as default |
| Auth | Shows API Key and/or IAM Token indicators |
| Status | Active (green) or Inactive (gray) |
| Actions | Test, Edit, Delete buttons |

### Adding Configuration

1. Click **Add Config** button
2. Select provider - form fields change based on selection
3. Fill in the required fields (see provider-specific sections below)
4. Optionally click **Test** to verify connection before saving
5. Click **Create**

### Common Fields (All Providers)

| Field | Description | Required |
|-------|-------------|----------|
| Name | Configuration name (e.g., "Production Claude") | Yes |
| Provider | LLM provider from dropdown | Yes |
| Model | Model name (entered manually) | Yes |
| Temperature | 0 (deterministic) to 1 (creative), default 0.3 | No |
| Max Tokens | Maximum response length, 100-8000, default 2000 | No |
| Active | Enable/disable this configuration | No |
| Default | Set as default configuration | No |

### Provider-Specific Fields

#### YandexGPT

| Field | Description | Required |
|-------|-------------|----------|
| Yandex Cloud Folder ID | Folder where YandexGPT is enabled | Yes |
| API Key | Yandex Cloud API key | No* |
| IAM Token | Alternative to API key (expires after 12h) | No* |

*Either API Key or IAM Token is required. Models: `yandexgpt-5-lite`, `yandexgpt-5`.

#### OpenAI

| Field | Description | Required |
|-------|-------------|----------|
| API Key | OpenAI API key (sk-...) | Yes |
| Base URL | Custom endpoint (default: api.openai.com) | No |

Models: `gpt-4o`, `gpt-4-turbo`, `gpt-3.5-turbo`.

#### Azure OpenAI

| Field | Description | Required |
|-------|-------------|----------|
| Base URL | Azure resource endpoint (https://your-resource.openai.azure.com) | Yes |
| API Key | Azure OpenAI API key | Yes |

Models: your deployed model name.

#### Anthropic

| Field | Description | Required |
|-------|-------------|----------|
| API Key | Anthropic API key (sk-ant-...) | Yes |

Models: `claude-sonnet-4-20250514`, `claude-opus-4-20250514`, `claude-haiku-4-5-20251001`.

#### AWS Bedrock

| Field | Description | Required |
|-------|-------------|----------|
| AWS Region | Region where Bedrock is enabled (e.g., us-east-1) | Yes |
| AWS Credentials | ACCESS_KEY_ID:SECRET_ACCESS_KEY (colon-separated) | No |

Leave credentials empty to use IAM Role on EC2 instances. Models: `us.anthropic.claude-sonnet-4-5-20250929-v1:0`, `amazon.titan-text-premier-v1:0`.

#### Google Vertex AI

Two modes:

**Express Mode** (recommended for Gemini):
- Leave Project ID:Region empty
- Enter API key in Access Token field
- No project or region needed

**Full Mode** (for Claude on Vertex):
- Enter `project-id:region` in Project ID:Region field
- Enter OAuth2 access token in Access Token field

| Field | Description | Required |
|-------|-------------|----------|
| Project ID:Region | GCP project:region for Full Mode (leave empty for Express) | No |
| Access Token | API key (Express) or OAuth2 token (Full) | No |

Models: `gemini-2.5-flash-lite`, `gemini-2.5-pro`, `claude-sonnet-4-5@20250929`.

#### Custom (OpenAI-compatible)

For self-hosted models: Ollama, Mistral, vLLM, LiteLLM, LocalAI.

| Field | Description | Required |
|-------|-------------|----------|
| Base URL | Endpoint URL (e.g., http://localhost:11434/v1) | Yes |
| API Key | API key if required by the endpoint | No |

Models: depends on your deployment (e.g., `llama3.1`, `mistral`, `codestral`).

### Editing Configuration

1. Click **Edit** button on a configuration row
2. Modify fields - API key/credentials can be left empty to keep the current value
3. Click **Update**

When editing, credentials are not displayed for security. Leave the field empty to preserve the existing key.

### Testing Configuration

Two ways to test:

**From the table** (saved configs):
1. Click **Test** button on a configuration row
2. Uses the saved credentials - no need to re-enter

**From the form** (before saving):
1. Fill in the configuration form
2. Click **Test** button in the form
3. If editing an existing config with no new credentials, the test uses the saved credentials

Test results show:
- Response text from the LLM
- Input/Output token counts
- Duration in milliseconds
- Error details on failure

### Default Configuration

One configuration should be marked as default. The default is used when no specific config is selected in the chat or when AI features are invoked from other pages (rule explanation, diagnosis).

If no default is set:
- A warning appears: "No default config set!"
- The system falls back to any active configuration
- A warning is included in AI responses

Toggle the **Default Config** switch in the table to set/unset.

### Deleting Configuration

1. Click **Delete** button on a configuration row
2. Confirm deletion - all related usage history is also deleted

## Chat Interface

### Starting a Conversation

1. Go to **AI Tools > AI Assistant**
2. Optionally select a specific configuration from the dropdown
3. Type your question in the input field
4. Press Enter or click **Send**

### Language

The AI assistant responds in the language selected in the UI (English or Russian), regardless of the language of your question. This prevents random language responses when input is ambiguous.

### Chat Features

- **Markdown Support** - AI responses render as formatted text with headings, lists, and code blocks
- **Configuration Selector** - choose which LLM config to use per conversation
- **Auto-scroll** - chat scrolls to show new messages
- **Token Limit Warning** - notifies when max tokens is reached

### Example Questions

- "What is CIS benchmark rule 1.1.1.1?"
- "How do I fix SSH configuration issues?"
- "What profile should I use for a web server running Ubuntu 24.04?"
- "Explain the difference between Level 1 and Level 2"
- "Why might hardening disable my application?"

### Clearing Chat

Click **Clear** button to start a new conversation.

## AI Features in Other Pages

### Rule Explanation (Compliance Page)

When LLM is configured, an **Explain** button appears in compliance scan results:

1. View scan results for a completed scan
2. Click **Explain** button on a rule row
3. A modal shows AI-generated explanation:
   - What the rule checks
   - Why it matters for security
   - Risks of non-compliance
   - How to fix it in simple steps

The explanation is generated in the UI language (English or Russian).

### Failure Diagnosis (Jobs Page)

When a hardening job fails:

1. Go to Jobs page
2. Click **Diagnose with AI** on a failed job
3. AI analyzes the Ansible output and provides:
   - Root cause analysis
   - Fix steps
   - Prevention tips
   - Severity assessment

## Usage Statistics

The Usage tab shows aggregate and per-provider statistics for the last 30 days:

| Metric | Description |
|--------|-------------|
| Total Requests | Number of AI API calls across all providers |
| Input Tokens | Total tokens sent to all providers |
| Output Tokens | Total tokens received from all providers |

The per-provider breakdown table shows:

| Column | Description |
|--------|-------------|
| Provider | LLM provider name |
| Model | Model used |
| Total Requests | Requests for this provider/model |
| Input Tokens | Tokens sent |
| Output Tokens | Tokens received |

## Credential Security

All API keys, IAM tokens, and credentials are encrypted at rest using AES-256-GCM before storage in the database. They are never returned in API responses - only a boolean indicator (has_api_key, has_iam_token) is shown.

## Best Practices

### Configuration

- Set one configuration as **default** to avoid warnings
- Use lower temperature (0.3) for factual answers about CIS rules
- Use higher temperature (0.7) for creative troubleshooting suggestions
- Set reasonable max_tokens (2000 is a good default)

### Cost Control

- Disable unused configurations
- Monitor per-provider usage in the Usage tab
- Use smaller/faster models for routine queries
- Clear chat to reduce context length in long conversations

### Self-Hosted Models

For air-gapped or cost-sensitive deployments:
1. Deploy Ollama with a model (e.g., `ollama pull llama3.1`)
2. Create a Custom provider config with Base URL `http://ollama-host:11434/v1`
3. No API key needed for local Ollama

## Troubleshooting

### No Response from AI

1. Verify configuration is active and set as default
2. Test configuration with the Test button
3. Check API key is valid and not expired

### "Configure an LLM provider first"

No active LLM configuration exists:
1. Go to LLM Settings
2. Create a configuration for your provider
3. Mark it as Active and Default

### Configuration Test Fails

1. Verify API key/credentials are correct
2. For Bedrock: ensure the model is enabled in your AWS region
3. For Vertex AI Express: ensure API key is enabled for Vertex AI API in GCP Console
4. For Custom: verify the endpoint URL is accessible and returns OpenAI-compatible responses

### Wrong Language in Responses

The AI responds in the UI language (top-right language selector). Switch the UI language to get responses in the desired language.

## Provider Setup Guides

### YandexGPT

1. Go to Yandex Cloud Console > IAM > API Keys
2. Create a new API key, copy the secret
3. Get your Folder ID from the folder page
4. Create config: Provider=YandexGPT, Model=yandexgpt-5-lite, Folder ID, API Key

### Anthropic

1. Go to console.anthropic.com > API Keys
2. Create a key, copy it
3. Create config: Provider=Anthropic, Model=claude-sonnet-4-20250514, API Key

### AWS Bedrock

1. Enable model access in AWS Console > Bedrock > Model access
2. Create IAM user with `bedrock:InvokeModel` permission
3. Create config: Provider=AWS Bedrock, Region=us-east-1, Credentials=ACCESS_KEY:SECRET_KEY
4. Or leave credentials empty on EC2 with IAM Role attached

### Google Vertex AI (Express Mode)

1. Enable Vertex AI API in GCP Console
2. Create API key in Credentials page
3. Create config: Provider=Google Vertex AI, Model=gemini-2.5-flash-lite, Access Token=your-api-key
4. Leave Project ID:Region empty for Express Mode

### Ollama

**Self-hosted:**
1. Install Ollama: `curl -fsSL https://ollama.com/install.sh | sh`
2. Pull a model: `ollama pull llama3.1`
3. Create config: Provider=Custom, Model=llama3.1, Base URL=http://localhost:11434/v1

**Ollama Cloud:**
1. Get API key from your Ollama Cloud account
2. Create config: Provider=Custom, Model=llama3.1, Base URL=https://ollama.com/v1, API Key=your-key

## Related Pages

- [Compliance Scanning](/en/docs/haas/compliance-scanning/) - AI rule explanations in scan results
- [Settings](/en/docs/haas/settings/) - General platform settings
- [Troubleshooting](/en/docs/haas/troubleshooting/) - Platform diagnostics and must-gather tool