Security | Gokin

Gokin implements a multi-layered security system: permissions, sandbox, command validation, audit, and file protection.

Permission System (3 Levels)#

Level	Behavior	Tools
RiskLow	Auto-approved	read, glob, grep, tree, diff, env, list_dir, git_status, git_log, git_diff, git_blame, web_search, web_fetch, ask_user, memory, code_graph, semantic_search, history_search, task_output, task_stop, todo
RiskMedium	Ask once, then auto-approve	write, edit, git_add, copy, move, mkdir, task, batch
RiskHigh	Ask every time	bash, delete, git_commit, ssh

User Decisions#

Decision	Description
Allow	Allow once
AllowSession	Allow for the entire session
Deny	Deny once
DenySession	Deny for the entire session

RiskMedium tools are automatically approved after the first Allow until session end (stored in autoApprovedTools).

Permission Caching#

LRU cache: 1000 entries, TTL 24 hours
Cache keys include tool arguments (bash command, file path)

Bash Sandbox#

All bash commands run in an isolated environment.

Restrictions#

Working directory — commands restricted to current project
Environment — sanitized: only safe variables
Timeout — SIGTERM → SIGKILL on timeout

Safe Environment Variables#

PATH, HOME, USER, TERM, LANG, LC_ALL, PWD,
TMPDIR, SHELL, GOPATH, GOROOT, GOPROXY,
NODE_PATH, PYTHONPATH, VIRTUAL_ENV, EDITOR, VISUAL

All other environment variables are removed before execution.

Sandbox Configuration#

tools:
  bash_sandbox: true               # Enable sandbox

Full chroot/seccomp is only available on Linux. macOS and Windows use basic isolation.

Command Validation#

Three levels of checking before executing bash commands.

Blocked Commands (exact match)#

Fork bombs: :(){:|:&};: and variants

Blocked Substrings (60+ patterns)#

Destructive file operations:

rm -rf /, rm -rf /*, rm -fr /, rm -fr /*

Disk operations:

mkfs., > /dev/sda, dd if=/dev/zero of=/dev/sd*

System:

chmod -R 777 /, chown -R root /
insmod, rmmod, modprobe, /proc/sys, /sys/kernel
/boot/, grub-install, update-grub

Network attacks:

nc -e, nc -c, bash -i >& /dev/tcp, /dev/tcp/, /dev/udp/

Sensitive file access:

/etc/shadow, /etc/passwd, .ssh/id_rsa, .aws/credentials, .kube/config

Environment injection:

LD_PRELOAD=, LD_LIBRARY_PATH=, DYLD_INSERT_LIBRARIES=

Credential theft:

mimikatz, hashdump, secretsdump

Blocked Regex Patterns (30+)#

Fork bombs:

:(){, $0 & $0, while true; do ... &

Recursive deletion:

rm (-[rRf]+\s+)+/

Malicious code download:

(wget|curl).*\|\s*(ba)?sh
base64 -d.*\|\s*(ba)?sh

Reverse shells:

python[23]? -c.*socket.*exec
perl -e.*socket.*exec

SSH injection:

echo.*>>\s*.*authorized_keys

Crontab manipulation:

echo.*>>\s*/etc/cron
echo.*>>\s*/var/spool/cron

History clearing:

~/\..*history, history -c, unset HISTFILE

Shell injection:

eval.*(base64|curl|wget|nc\b)

Validation Result Levels#

Level	Description
blocked	Command blocked, execution denied
caution	Suspicious but allowed (warning)
safe	Safe

File System Protection#

Path Validator#

Null byte detection — prevents null byte injection
Symlink resolution — filepath.EvalSymlinks (atomic, TOCTOU protection)
Directory traversal — blocks ../ and escaping working directory
Cross-drive paths — handles cross-drive paths (Windows)
Normalization — filepath.Clean for canonical paths
Name sanitization — removes dangerous characters from filenames

Methods#

Method	Description
`Validate(path)`	Full path validation
`ValidateFile(path)`	File check (parent directory existence)
`ValidateDir(path)`	Directory check
`SanitizeFilename(name)`	Remove dangerous characters
`JoinPathSafe(base, rel)`	Safe path joining

SSH Validation#

Blocks dangerous SSH commands (fork bombs, destructive operations)
Blocks hosts: localhost, 127.0.0.1, ::1
Supports allowed/blocked host lists
IP address validation

Audit Logging#

Audit Entry Structure#

Entry {
    ID        string         // UUID
    Timestamp time.Time
    ToolName  string         // Tool name
    Args      map[string]any // Arguments (sanitized)
    Result    string         // Result (truncated)
    Success   bool
    Error     string
    Duration  time.Duration
    SessionID string
}

Configuration#

Parameter	Default	Description
`enabled`	`true`	Enable audit
`max_entries`	`10000`	Max entries per session
`max_result_len`	`1000`	Max result length
`retention_days`	`30`	Retention (days)

Features#

Per-session files: ~/.config/gokin/audit/{sessionID}.json
File permissions: 0600 (owner only)
Debounced saves: writes every 2 seconds (coalescing)
Secret redaction: SecretRedactor masks sensitive values
Retention: automatic deletion of entries past retention period
Export: JSON or JSONL
Statistics: breakdown by tool, success/error counts, average time

Recommendations#

Storing API Keys#

Environment variables (recommended):

export GOKIN_GEMINI_KEY="your-key"
export GOKIN_ANTHROPIC_KEY="your-key"

Config file (less secure):
```
api:
  gemini_key: "your-key"
```
OAuth (for Gemini — no key storage):
```
/oauth-login
```

Working in Sensitive Environments#

Enable bash_sandbox: true (enabled by default)
Use allowed_directories to restrict access
Review audit logs: /ledger, /journal
Use /permissions on for forced prompts
Limit fallback_providers to trusted providers