> For the complete documentation index, see [llms.txt](https://docs.viesus.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.viesus.com/operations/security.md).

# Security

Security guidance for production VIESUS deployments — protecting your license credentials, hardening any API you expose, isolating the service on the network, and locking down containers.

***

## GUID and API key management

The GUID (on-premise) and API key (VIESUS Cloud) are credentials that allow VIESUS processing under your license. Treat them like passwords.

### What to avoid

| Action                                               | Why it's a risk                                           |
| ---------------------------------------------------- | --------------------------------------------------------- |
| Hardcode GUID in source code                         | GUID visible to anyone with code access or in git history |
| Commit GUID to version control                       | Credentials in git history are hard to revoke completely  |
| Log the GUID                                         | Credentials in log aggregators and monitoring tools       |
| Pass GUID as a command-line argument visible in `ps` | Visible to all users on the system                        |
| Bake GUID into a Docker image                        | Image layers store the value, visible in registries       |

### Recommended patterns

**Environment variables:**

```bash
export VIESUS_GUID="$(cat /run/secrets/viesus_guid)"
node server.js
```

**Secrets manager (AWS Secrets Manager example):**

```js
const { SecretsManagerClient, GetSecretValueCommand } = require('@aws-sdk/client-secrets-manager');

async function getGuid() {
  const client = new SecretsManagerClient({ region: 'eu-west-1' });
  const response = await client.send(
    new GetSecretValueCommand({ SecretId: 'viesus/guid' })
  );
  return response.SecretString;
}

const GUID = await getGuid();
```

**Docker secrets (Swarm):**

```bash
echo "your-guid" | docker secret create viesus_guid -
```

```js
// Read from Docker secret file
const GUID = process.env.VIESUS_GUID ||
  fs.readFileSync('/run/secrets/viesus_guid', 'utf8').trim();
```

***

## GUID rotation

GUID-based licenses use the same GUID throughout the license term. When the license renews, the GUID stays the same but the library package is updated.

**If a GUID is compromised:**

1. Contact <info@viesus.com> immediately to request a GUID replacement.
2. Update the GUID in all running services.
3. Audit access to determine how the GUID was exposed.

***

## API surface hardening (Node.js service)

If you expose an HTTP API wrapping the VIESUS Node.js module:

**Validate and restrict file inputs:**

```js
const ALLOWED_MIME_TYPES = new Set(['image/jpeg', 'image/png', 'image/tiff', 'image/webp']);
const MAX_FILE_SIZE = 50 * 1024 * 1024; // 50 MB

app.post('/enhance', upload.single('image'), (req, res, next) => {
  if (!req.file) return res.status(400).json({ error: 'No file provided' });
  if (!ALLOWED_MIME_TYPES.has(req.file.mimetype)) {
    fs.unlink(req.file.path, () => {});
    return res.status(415).json({ error: 'Unsupported file type' });
  }
  if (req.file.size > MAX_FILE_SIZE) {
    fs.unlink(req.file.path, () => {});
    return res.status(413).json({ error: 'File too large' });
  }
  next();
});
```

**Restrict file paths to known directories:**

```js
const OUTPUT_DIR = path.resolve('./outputs');

function safeOutputPath(jobId, ext) {
  const filename = `${jobId}${ext}`;
  const full = path.join(OUTPUT_DIR, filename);
  // Prevent path traversal
  if (!full.startsWith(OUTPUT_DIR + path.sep)) {
    throw new Error('Invalid path');
  }
  return full;
}
```

**Rate limiting:**

```js
const rateLimit = require('express-rate-limit');

app.use('/enhance', rateLimit({
  windowMs: 60 * 1000, // 1 minute
  max: 20,             // 20 uploads per IP per minute
  message: { error: 'Too many requests' },
}));
```

***

## Network isolation

On-premise VIESUS deployments make **no outbound network connections** for licensing. GUID licenses are passed at runtime, and Activation Keys (also called Software Keys) are activated **offline** via a request/activation-file exchange — neither contacts a license server at runtime, so the service can run fully air-gapped.

**Firewall recommendations:**

| Direction                    | Rule                                                        |
| ---------------------------- | ----------------------------------------------------------- |
| Inbound to VIESUS service    | Allow only from your application servers or load balancer   |
| Outbound from VIESUS service | Deny all — on-premise licensing requires no internet access |

**Docker network isolation:**

```yaml
# docker-compose.yml
services:
  viesus-enhance:
    networks:
      - internal

  nginx:
    networks:
      - internal
      - external

networks:
  internal:
    internal: true   # No internet access
  external:
```

***

## Docker security

**Run as a non-root user:**

```dockerfile
RUN useradd -r -s /bin/false viesus
USER viesus
```

**Read-only filesystem:**

```bash
docker run \
  --read-only \
  --tmpfs /tmp \
  --tmpfs /app/uploads \
  --tmpfs /app/outputs \
  viesus-enhance:latest
```

**Drop capabilities:**

```yaml
cap_drop:
  - ALL
cap_add:
  - NET_BIND_SERVICE  # only if binding port < 1024
security_opt:
  - no-new-privileges:true
```

***

## Webhook endpoint security

When receiving VIESUS Cloud webhooks, always verify the HMAC signature before processing:

```js
function verifyWebhook(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  // Use timingSafeEqual to prevent timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(signatureHeader, 'hex')
  );
}
```

Never skip signature verification even for development — the webhook endpoint may receive untrusted external traffic.

***

## Input file security

VIESUS processes image files. Malformed or malicious images (designed to exploit image parsing) are a theoretical concern for any image processing pipeline. Mitigations:

* Run VIESUS in an isolated environment (container or VM) with no access to sensitive data
* Do not process user-uploaded files as the same OS user that has access to credentials or other sensitive system resources
* Scan inputs with a virus scanner for enterprise deployments accepting external files


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.viesus.com/operations/security.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.