This guide explains how to use ARX security tools with OpenAI's GPT-4 via function calling.

Overview

The ARX OpenAI integration allows you to:

• Use ARX tools in OpenAI applications - Call security operations directly from your OpenAI-powered agents
• Unified tool interface - Same 8 tools work identically across Claude Code (MCP) and OpenAI clients
• HTTP API access - RESTful endpoints for discovering and executing tools
• Authentication support - Optional API key authentication for secure deployments

Architecture

`` OpenAI Client ↓ ARX OpenAI Server (HTTP on port 8001) ↓ ARX MCP Server (shared core) ↓ Backend APIs (ARXSEC, etc.) ``

Quick Start

1. Start the ARX OpenAI Server

```bash

With API key authentication (recommended for production)

OPENAI_SERVER_API_KEY=your-secret-key python openai_server.py

Without authentication (development only)

python openai_server.py ```

The server starts on http://localhost:8001.

2. Discover Available Tools

``bash curl http://localhost:8001/openai/functions ``

Response: ``json { "functions": [ { "name": "run_security_scan", "description": "Execute a security scan...", "parameters": { ... } }, ... ], "count": 8 } ``

3. Use in OpenAI Client

```python import os import requests from openai import OpenAI

Get available tools

response = requests.get("http://localhost:8001/openai/functions") functions = response.json()["functions"]

Create OpenAI client

client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

Call with function definition

response = client.chat.completions.create( model="gpt-4", messages=[{ "role": "user", "content": "Run a SAST scan on https://github.com/example/repo" }], functions=functions, function_call="auto" )

When OpenAI calls a function, forward to ARX

if response.choices[0].message.function_call: func_call = response.choices[0].message.function_call result = requests.post( "http://localhost:8001/openai/call_tool", json={ "function_name": func_call.name, "arguments": json.loads(func_call.arguments) } ) ```

API Reference

GET /health

Health check endpoint.

Response: ``json { "status": "healthy", "service": "arx-openai-server" } ``

GET /openai/functions

Discover all available ARX tools in OpenAI function format.

Query Parameters:

• Authorization: Bearer <api-key> (optional, if OPENAI_SERVER_API_KEY is set)

Response: ``json { "functions": [ { "name": "run_security_scan", "description": "Execute a security scan...", "parameters": { "type": "object", "properties": { ... }, "required": ["scan_type", "target"] } }, ... ], "count": 8 } ``

POST /openai/call_tool

Execute a tool and return results.

Headers:

• Content-Type: application/json
• Authorization: Bearer <api-key> (optional, if OPENAI_SERVER_API_KEY is set)

Request Body: ``json { "function_name": "run_security_scan", "arguments": { "scan_type": "sast", "target": "https://github.com/example/repo", "policy_id": "policy-123", "require_approval": false } } ``

Response: ``json { "function_name": "run_security_scan", "content": [ { "type": "text", "text": "{\"scan_id\": \"scan-123\", \"status\": \"completed\", \"findings\": 5}" } ], "isError": false } ``

Available Tools

The OpenAI server exposes these 8 ARX security tools:

1. run_security_scan

Execute security scans (SAST, DAST, SCA, container, IAC, SBOM, AppSec).

Parameters:

• scan_type (required): Type of scan
• target (required): Target to scan
• policy_id (optional): Policy ID to enforce
• require_approval (optional): Require human approval

2. execute_remediation

Execute remediation actions for security findings.

Parameters:

• finding_id (required): ID of the finding
• action (required): Remediation action
• require_approval (optional): Require human approval

3. check_compliance

Check compliance against frameworks (SOC2, ISO27001, HIPAA, PCI-DSS, GDPR).

Parameters:

• framework (required): Compliance framework
• scope (optional): Scope of check

4. manage_secrets

Manage secrets with encryption, rotation, and audit.

Parameters:

• operation (required): create, retrieve, rotate, or revoke
• secret_name (required): Secret name
• secret_value (optional): Secret value for create operation

5. request_approval

Request human approval for sensitive operations.

Parameters:

• operation (required): Operation description
• reason (optional): Reason for operation
• priority (optional): Priority level (low, medium, high, critical)

6. get_audit_log

Retrieve audit logs for compliance and investigation.

Parameters:

• filters (optional): Audit log filters
• limit (optional): Maximum records to return

7. list_connectors

List available security connectors and integrations.

Parameters:

• connector_type (optional): Filter by type (sast, cloud, iam, etc.)

8. manage_policies

Create, update, or retrieve security policies.

Parameters:

• operation (required): create, retrieve, update, delete, or list
• policy_id (optional): Policy ID
• policy_definition (optional): Policy configuration

Configuration

Environment Variables

```bash

OpenAI Server Configuration

OPENAI_SERVER_PORT=8001 # HTTP server port (default: 8001) OPENAI_SERVER_API_KEY=your-secret-key # API key for authentication (optional)

ARX Backend Configuration

ARXSEC_API_URL=http://localhost:8000 # ARX backend API URL ARXSEC_API_KEY=arxsec-api-key # ARX API key

Logging

LOG_LEVEL=INFO # Log level (DEBUG, INFO, WARNING, ERROR) ```

Examples

Example 1: Run a Security Scan

```python import requests import json

Execute scan

result = requests.post("http://localhost:8001/openai/call_tool", json={ "function_name": "run_security_scan", "arguments": { "scan_type": "sast", "target": "https://github.com/example/repo" } })

print(json.dumps(result.json(), indent=2)) ```

Example 2: Check Compliance Status

```python result = requests.post("http://localhost:8001/openai/call_tool", json={ "function_name": "check_compliance", "arguments": { "framework": "SOC2", "scope": "production" } })

compliance = result.json() print(f"Compliant: {compliance['content'][0]['text']}") ```

Example 3: Request Approval

```python result = requests.post("http://localhost:8001/openai/call_tool", json={ "function_name": "request_approval", "arguments": { "operation": "Deploy to production", "reason": "Release v1.0.0", "priority": "high" } })

approval = result.json() print(f"Approval ID: {approval['content'][0]['text']}") ```

Running with OpenAI

See openai_client_example.py for a complete example of using ARX tools with OpenAI's GPT-4.

```bash

Install OpenAI SDK

pip install openai

Set your OpenAI API key

export OPENAI_API_KEY=sk-...

Run the example

python openai_client_example.py ```

Deployment

Docker

```bash

Build image

docker build -t arx-openai-server .

Run container

docker run -p 8001:8001 \ -e OPENAI_SERVER_API_KEY=your-secret-key \ -e ARXSEC_API_URL=http://arxsec:8000 \ -e ARXSEC_API_KEY=arxsec-key \ arx-openai-server ```

Kubernetes

```yaml apiVersion: apps/v1 kind: Deployment metadata: name: arx-openai-server spec: replicas: 2 selector: matchLabels: app: arx-openai-server template: metadata: labels: app: arx-openai-server spec: containers:

• name: openai-server

image: arx-openai-server:latest ports:

• containerPort: 8001

env:

• name: OPENAI_SERVER_API_KEY

valueFrom: secretKeyRef: name: arx-secrets key: openai-api-key

• name: ARXSEC_API_URL

value: http://arxsec:8000

• name: ARXSEC_API_KEY

valueFrom: secretKeyRef: name: arx-secrets key: arxsec-api-key ```

Security Considerations

1. API Key Authentication - Always set OPENAI_SERVER_API_KEY in production
2. HTTPS - Use HTTPS in production (put behind reverse proxy like nginx)
3. Network Access - Restrict access to the OpenAI server to trusted networks
4. Audit Logging - All tool calls are logged for compliance
5. Approval Workflows - Use require_approval flag for sensitive operations

Troubleshooting

"Connection refused" error

• Verify ARX OpenAI server is running: curl http://localhost:8001/health
• Check port 8001 is not in use: lsof -i :8001

"Invalid API key" error

• Ensure Authorization: Bearer <key> header is set correctly
• Verify OPENAI_SERVER_API_KEY matches the sent key

Tools not executing

• Check ARX backend is running: ARXSEC_API_URL
• Verify backend API key: ARXSEC_API_KEY
• Check server logs: tail -f logs/arx-openai-server.log

OpenAI function format errors

• Verify function definitions from /openai/functions are valid
• Check function parameters match the schema
• Ensure required parameters are provided

Support

For issues or questions:

1. Check logs: tail -f logs/arx-openai-server.log
2. Run health check: curl http://localhost:8001/health
3. Test tool discovery: curl http://localhost:8001/openai/functions
4. Review examples: See openai_client_example.py