Last Updated: February 21, 2026

This document outlines security considerations, best practices, and threat mitigations in Pluginator.

Pluginator operates with the following security principles:

1. Least Privilege - Only requests permissions needed for operation
2. Defense in Depth - Multiple layers of validation and protection
3. Fail Secure - Errors default to safe/conservative behavior
4. No Remote Code Execution - Never evaluates arbitrary code

• Path traversal attacks
• Malicious file downloads
• Configuration injection
• API credential exposure
• File integrity verification

• Operating system vulnerabilities
• Network-level attacks (MITM without HTTPS)
• Physical access to the server
• Vulnerabilities in downloaded plugins themselves

All file operations use safe path utilities:

// Safe path joining prevents traversal
const result = safePath('/base/dir', '../../../etc/passwd');
// result.valid === false
// result.error === 'Path traversal detected'

// Safe join throws on traversal attempts
safeJoin('/server/plugins', '../../../sensitive'); // Throws Error

Protected operations:

• Plugin file copying
• Backup creation
• Configuration file access
• Log file writing

Downloaded files have their names sanitized:

sanitizeFilename('plugin<script>.jar');     // 'pluginscript.jar'
sanitizeFilename('../../malicious.jar');    // 'malicious.jar'
sanitizeFilename('file:with:colons.jar');   // 'filewithcolons.jar'

Removed characters:

• Path separators (/, \)
• Special characters (<, >, :, ", |, ?, *)
• Control characters (\x00 - \x1f)
• Leading dots

All downloads can be verified against checksums:

const result = await verifyChecksum(filePath, expectedHash, 'sha256');
if (!result.valid) {
  // Delete the file, report error
}

Supported algorithms:

• SHA-256 (recommended)
• SHA-512
• SHA-1 (legacy)
• MD5 (legacy, not recommended)

All API communications use HTTPS:

• Spigot/Spiget API
• Modrinth API
• GitHub API
• CurseForge API
• Custom web manifests (configurable)

API credentials are handled securely:

# Store in environment variables (preferred)
export GITHUB_TOKEN=ghp_xxxxx

# Or in config file with restricted permissions
# chmod 600 config/pluginator.config
GITHUB_TOKEN=ghp_xxxxx

Never commit credentials to version control.

Session tokens are encrypted at rest to provide defense-in-depth protection:

Encryption Details:

• Algorithm: AES-256-GCM (authenticated encryption)
• Key derivation: PBKDF2 with 100,000 iterations (SHA-256)
• IV: 12 bytes (96 bits) per NIST recommendation
• Auth tag: 16 bytes (128 bits) for tamper detection

Key Material:

• Derived from machine-specific identifier (hostname, username, home directory, architecture)
• Salt stored in ~/.pluginator/.salt with 0o600 permissions
• Key buffers are zeroed after use to minimize memory exposure

Session File Format (v2):

{
  "version": 2,
  "iv": "<base64-encoded-12-byte-iv>",
  "authTag": "<base64-encoded-16-byte-tag>",
  "ciphertext": "<base64-encoded-encrypted-session>"
}

Threat Mitigations:

Backward Compatibility:

• Plaintext sessions (v1) are still readable
• Automatically upgraded to encrypted (v2) on next save
• No manual migration required

CLI Commands:

# Check session encryption status
pluginator auth status

# Manually migrate to encrypted format
pluginator auth migrate

# Clear session (logout)
pluginator auth clear

Recommended permissions:

# User data directory
chmod 700 ~/.pluginator/

# Configuration files
chmod 600 ~/.pluginator/config.json
chmod 600 ~/.pluginator/session.json

# Data directories
chmod 700 ~/.pluginator/backups/
chmod 700 ~/.pluginator/logs/
chmod 700 ~/.pluginator/cache/

All configuration is validated with Zod schemas:

// Paths are validated
PROD_SERVER_PATH: z.string().min(1)

// Numbers have bounds
MAX_BACKUPS: z.number().int().min(1).max(100)

// URLs are validated
apiUrl: z.string().url()

Environment variables override config files, allowing secure CI/CD:

# Override without modifying files
PROD_SERVER_PATH=/secure/path pluginator sync

Built-in rate limiting prevents abuse:

All HTTP requests have hardcoded timeouts (8-10 seconds) to prevent hanging connections.

Proper identification in requests:

The User-Agent header is dynamically set from package.json version (e.g., Pluginator/2.3.0).

Backups are tar.gz archives with predictable structure:

• No symlinks followed (prevents symlink attacks)
• No device files included
• No setuid/setgid bits preserved

Automatic cleanup prevents disk exhaustion. Configure max backup count in ~/.pluginator/config.json.

Backups are stored in ~/.pluginator/backups/ by default.

Logs are sanitized to avoid exposing:

• API tokens
• Passwords
• Full file paths (when possible)

Log files are created daily and automatically cleaned up.

chmod 600 ~/.pluginator/logs/*.log

• Minimal dependency footprint
• Regular dependency audits
• No arbitrary code execution (eval, etc.)

All changes undergo review for:

• Input validation
• Path handling
• Error handling
• Credential exposure

Do not report security vulnerabilities publicly.

Contact: Open a private security advisory or reach out via GitHub profile

Include:

1. Description of the vulnerability
2. Steps to reproduce
3. Potential impact
4. Suggested fix (if any)

Response timeline:

• Acknowledgment: 48 hours
• Assessment: 7 days
• Fix (if confirmed): 30 days

• Set restrictive permissions on config files
• Use environment variables for API tokens
• Verify server paths are correct
• Enable HTTPS for custom web manifests

• Keep Pluginator updated
• Review logs for anomalies
• Audit plugin sources periodically
• Verify backup integrity

• Run as non-root user
• Use dedicated service account
• Restrict network access if possible
• Monitor for unauthorized changes

1. Plugin Content - Pluginator cannot verify the safety of plugin contents
2. Source Trust - Relies on source repositories for plugin safety
3. Network Security - Assumes secure network between client and APIs
4. Local Access - Cannot protect against malicious local users

Pluginator is designed to support:

• General data protection best practices
• Secure software development lifecycle
• Industry-standard encryption (HTTPS/TLS)

For specific compliance requirements (GDPR, SOC2, etc.), additional measures may be needed at the deployment level.