Skip to main content
Mole checking authentication

Authentication

Muti Metroo supports multiple authentication mechanisms for different components.

Authentication Overview​

ComponentMechanismPurpose
Peer connectionsTLS/mTLSAgent-to-agent authentication
SOCKS5 proxyUsername/passwordClient authentication
RPCbcrypt passwordCommand authorization
File transferbcrypt passwordTransfer authorization
HTTP APINone (use firewall)Monitoring endpoints

SOCKS5 Authentication​

Configuration​

socks5:
  enabled: true
  address: "127.0.0.1:1080"
  auth:
    enabled: true
    users:
      - username: "user1"
        password_hash: "$2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy"
      - username: "user2"
        password_hash: "$2a$12$..."

Generating Password Hashes​

The recommended way to generate bcrypt password hashes is using the built-in CLI command:

# Interactive (recommended - password hidden)
muti-metroo hash

# Or provide password as argument
muti-metroo hash "yourpassword"

# With custom cost factor
muti-metroo hash --cost 12

See Generating Password Hashes for detailed documentation.

Alternative Methods​

Using htpasswd:

htpasswd -bnBC 10 "" yourpassword | tr -d ':\n'

Using Python:

import bcrypt
print(bcrypt.hashpw(b"yourpassword", bcrypt.gensalt(10)).decode())

Using Node.js:

const bcrypt = require('bcrypt');
console.log(bcrypt.hashSync('yourpassword', 10));

Cost Factor​

The cost factor (10, 12, etc.) determines hash computation time:

CostTime (approx)Recommendation
10~100msDevelopment
12~400msProduction
14~1.5sHigh security

Higher cost = slower brute force attacks, but also slower login.

Multiple Users​

socks5:
  auth:
    enabled: true
    users:
      - username: "admin"
        password_hash: "$2a$12$..."
      - username: "readonly"
        password_hash: "$2a$12$..."
      - username: "automation"
        password_hash: "$2a$10$..."

Client Usage​

# curl
curl -x socks5://user1:password@localhost:1080 https://example.com

# ssh
ssh -o ProxyCommand='nc -x localhost:1080 -P user1 %h %p' user@host

RPC Authentication​

Configuration​

rpc:
  enabled: true
  whitelist:
    - whoami
    - hostname
  password_hash: "$2a$12$..."
  timeout: 60s

Generating RPC Password Hash​

Use the built-in CLI command (see Generating Password Hashes):

muti-metroo hash --cost 12

Using RPC with Authentication​

CLI:

muti-metroo rpc -p myrpcpassword agent123 whoami

HTTP API:

curl -X POST http://localhost:8080/agents/agent123/rpc \
  -H "Content-Type: application/json" \
  -d '{"password":"myrpcpassword","command":"whoami"}'

File Transfer Authentication​

Configuration​

file_transfer:
  enabled: true
  password_hash: "$2a$12$..."
  allowed_paths:
    - /tmp
    - /home/user/uploads

Using File Transfer with Authentication​

# Upload
muti-metroo upload -p mypassword agent123 ./local.txt /tmp/remote.txt

# Download
muti-metroo download -p mypassword agent123 /tmp/remote.txt ./local.txt

HTTP API Authentication​

The HTTP API does not have built-in authentication. Secure it using:

Bind to Localhost​

http:
  enabled: true
  address: "127.0.0.1:8080"    # Only local access

Firewall Rules​

# Only allow from specific IP
iptables -A INPUT -p tcp --dport 8080 -s 10.0.0.100 -j ACCEPT
iptables -A INPUT -p tcp --dport 8080 -j DROP

Reverse Proxy with Auth​

nginx example:

server {
    listen 443 ssl;
    server_name metrics.example.com;

    auth_basic "Restricted";
    auth_basic_user_file /etc/nginx/.htpasswd;

    location / {
        proxy_pass http://127.0.0.1:8080;
    }
}

Environment Variables​

Never hardcode passwords in config files:

socks5:
  auth:
    users:
      - username: "${SOCKS5_USER}"
        password_hash: "${SOCKS5_PASSWORD_HASH}"

rpc:
  password_hash: "${RPC_PASSWORD_HASH}"

file_transfer:
  password_hash: "${FILE_TRANSFER_PASSWORD_HASH}"

Best Practices​

Password Security​

  1. Use strong passwords: 16+ characters, random
  2. Use high cost factor: 12+ for production
  3. Rotate passwords regularly: Especially if exposed
  4. Never share passwords: Per-user or per-system credentials

Defense in Depth​

Layer multiple security mechanisms:

# Localhost binding + authentication
socks5:
  address: "127.0.0.1:1080"    # Only local
  auth:
    enabled: true              # And authenticated

Monitoring​

Track authentication failures:

# Check SOCKS5 auth failures
curl http://localhost:8080/metrics | grep socks5_auth_failures

# Check RPC auth failures
curl http://localhost:8080/metrics | grep rpc.*auth_failed

Alert on:

  • Spike in auth failures (brute force attempt)
  • Auth failures from unexpected IPs
  • Successful auth at unusual times

Troubleshooting​

Invalid Password Hash​

Error: invalid bcrypt hash
  • Verify hash starts with $2a$ or $2b$
  • Check hash was generated correctly
  • Ensure no extra whitespace

Authentication Failed​

Error: authentication failed
  • Verify password is correct
  • Check password hash in config
  • Enable debug logging

User Not Found​

Error: user not found
  • Check username spelling
  • Verify user is in config
  • Username is case-sensitive

Next Steps​