Introducing Sneak Link: A Lightweight Tool for Secure Link-Based Access Control

What is Sneak Link and how does it provide secure access to self-hosted services? Sneak Link is a lightweight, open-source tool that enables secure link-based access control by verifying URL “knocks” on shared links and issuing cookies for protected services, eliminating the need for IP whitelisting while incorporating built-in observability and monitoring features.

This article answers the central question: “What is Sneak Link and how can it help secure sharing from self-hosted services like NextCloud or Immich?” It explores the tool’s features, setup, and benefits, drawing directly from its core design to provide practical insights for technical users.

What is Sneak Link?

Sneak Link verifies a URL “knock” on a shared link and issues a cookie granting access to protected services, supporting NextCloud, Immich, Paperless-ngx, and Photoprism with an extensible architecture. This approach allows secure external sharing without exposing services directly to the internet.

Summary: This section introduces Sneak Link as a tool for access control, highlighting its core mechanism and supported services for secure sharing.

Central question: “What exactly is Sneak Link and what does it do?”

Sneak Link operates as a proxy that sits between the public internet and your private self-hosted services. When a user accesses a shared link, the tool checks if the share exists by querying the internal service for an HTTP 200 status. If valid, it grants access via a cookie for most services or direct proxy for others like Paperless-ngx. This eliminates traditional barriers like VPNs or IP restrictions, making it ideal for sharing with non-technical users such as family or clients.

Consider an application scenario where you run a home server with personal photos in Immich. Instead of opening ports or setting up complex authentication, Sneak Link acts as the gatekeeper: external users click a share link, the tool validates it internally, and proxies the request if approved. This keeps your Immich instance on a private network, reducing exposure risks.

For an operational example, imagine sharing a family album via https://immich.yourdomain.com/share/XyZ789. Sneak Link receives the request, identifies the service by hostname, checks the internal Immich for validity, and issues a cookie allowing the user to browse the album seamlessly. If the share is invalid (e.g., returns 404), access is denied, preventing unauthorized probes.

Author’s reflection: In designing tools like this, I’ve learned that simplicity in access control can significantly enhance usability without sacrificing security—focusing on URL validation rather than user accounts streamlines the process for everyday sharing scenarios.

The extensible architecture means you can adapt it for other services by configuring additional URLs, though the core remains focused on the listed ones. This modularity ensures long-term relevance as your setup evolves.

Key Features of Sneak Link

Sneak Link offers URL-knocking to verify access, cookie-based token storage for sessions, rate limiting for security, and no requirement for IP whitelisting. For Paperless-ngx, it provides direct access restricted to /share/-prefixed paths without sessions.

Summary: This subsection outlines the primary features that make Sneak Link effective for secure access, emphasizing its security and ease-of-use aspects.

Central question: “What are the main features of Sneak Link that support secure sharing?”

These features work together to create a robust yet minimalistic access layer. URL-knocking acts as the initial trigger: users “knock” by visiting the shared URL, prompting verification. Once confirmed, a token is stored in a cookie, validating subsequent requests until expiration.

In an application scenario, rate limiting protects against brute-force attacks on share URLs. If someone tries guessing links repeatedly, the tool caps requests per IP within a time window, logging the event for review.

An operational example involves NextCloud sharing: you generate /s/AbCdEf123, send it out, and Sneak Link enforces rate limits (default 10 requests per 300 seconds). Exceeding this triggers a denial, safeguarding your shares.

Bullet points for clarity:

  • URL-knocking trigger: Initiates verification on link access.
  • Token in cookie: Enables session-based access for services like NextCloud.
  • Rate limiting: Tracks and blocks excessive attempts.
  • Security event tracking: Logs incidents for monitoring.
  • No IP whitelisting: Allows access from any location with a valid link.

Author’s reflection: From experience with similar systems, integrating rate limiting early prevents common vulnerabilities, teaching me that proactive security measures like this are essential for tools handling public-facing traffic.

This setup ensures compatibility with the supported services, where Paperless-ngx’s direct proxy avoids cookies for single-request efficiency, aligning with its document-serving nature.

Built-in Observability in Sneak Link

Sneak Link includes a real-time web dashboard for system metrics and analytics, a Prometheus metrics endpoint for integration, historical data tracking via SQLite, and session analytics with request logging. These tools provide insights into performance, security events, and user activity.

Summary: Here, we detail the observability components that allow monitoring of Sneak Link’s operations, from dashboards to metrics.

Central question: “How does Sneak Link support monitoring and observability for its users?”

The dashboard offers real-time views, including system metrics, active sessions with geolocation, and dark/light mode for usability. Prometheus integration exposes metrics like HTTP requests, security events, and uptime at a dedicated endpoint.

An application scenario is monitoring a shared Photoprism collection during a family event. The dashboard shows active sessions, helping you track who accesses what and from where, while Prometheus feeds data to Grafana for alerts on unusual activity.

For an operational example, after deployment, access http://your-host:3000/ to view metrics. If a rate limit is hit, it appears in security metrics, allowing quick response.

Sneak Link Dashboard

Image source: From the tool’s documentation.

Dashboard features in bullets:

  • Real-time system metrics.
  • Active session tracking with geolocation data.
  • Dark/light mode support.

Prometheus features:

  • Standard metrics at /metrics.
  • HTTP request details (count, duration, codes).
  • Security and rate limiting metrics.
  • Service-specific validation.
  • Uptime and performance.

Author’s reflection: Implementing SQLite for persistence has shown me how lightweight databases can enable powerful historical analysis without overhead, a key lesson in balancing observability with minimal dependencies.

This integration makes Sneak Link suitable for production-like environments, where monitoring is crucial.

Usage Scenario for Sneak Link

Sneak Link enables sharing content from self-hosted services like photos or documents with external users without VPNs or direct internet exposure. It proxies valid requests to private services based on hostname using local DNS.

Summary: This section describes practical use cases for deploying Sneak Link in sharing workflows.

Central question: “In what scenarios would I use Sneak Link to share content securely?”

Ideal for self-hosted setups, it allows sharing with family, friends, or clients. Your services remain private, while Sneak Link handles public validation.

Application scenario: Sharing client documents via Paperless-ngx. Generate a share link, send it, and Sneak Link ensures only valid accesses proxy through, keeping the service internal.

Operational example: For Immich, create /share/XyZ789 for an album. Recipient clicks https://immich.yourdomain.com/share/XyZ789, triggering validation and cookie issuance for access.

Steps in the flow:

  1. Create share links in services.
  2. Send complete URLs to recipients.
  3. Validation checks HTTP status.
  4. Grant access if valid.

Author’s reflection: Reflecting on usage, I’ve found that this scenario simplifies collaboration, reminding me how tools like Sneak Link bridge technical gaps for non-experts.

Network Setup for Sneak Link

In a local network, domains like nextcloud.yourdomain.com resolve to internal services via local DNS, handling web traffic. Publicly, the same domain resolves to your IP, where Sneak Link proxies based on hostname using local DNS.

Summary: Explains the network configuration needed for Sneak Link to function effectively.

Central question: “How do I set up my network to use Sneak Link?”

This split-brain DNS setup ensures internal resolution for services and public proxying via Sneak Link.

Application scenario: Home lab with multiple services. Local DNS points to private IPs, while public DNS directs to Sneak Link’s host.

Operational example: Configure DNS so locally nextcloud.yourdomain.com hits 192.168.1.10, publicly it hits your router forwarding to Sneak Link on port 8080.

Author’s reflection: Network setups like this have taught me the value of DNS flexibility in maintaining security layers.

Access Flow in Sneak Link

The access flow starts with creating share links in services, sending URLs, validating via HTTP status, and granting access through cookies or direct proxy. Rate limiting protects against brute force.

Summary: Details the step-by-step process users follow to access shared content.

Central question: “What is the step-by-step access flow when using Sneak Link?”

  1. Create shares: e.g., NextCloud /s/AbCdEf123.
  2. Send URLs: Full domain-included links.
  3. Validation: Check internal service for 200 OK.
  4. Access: Issue cookie or proxy.

Application scenario: Sharing Photoprism photos for a wedding. Links grant temporary access without accounts.

Operational example: User clicks Photoprism link /s/k2yta5ims0; valid check leads to cookie for browsing.

Author’s reflection: This flow’s transparency has reinforced for me the importance of clear validation in user trust.

Security Benefits of Sneak Link

Sneak Link provides no IP whitelisting needs, access only for valid shares, rate limiting against attacks, cookie-based sessions with expiration, and keeps services on private networks. This secures external sharing without technical barriers for recipients.

Summary: Highlights how Sneak Link enhances security in sharing setups.

Central question: “What security advantages does Sneak Link offer over traditional methods?”

Benefits include reduced exposure and automated protections.

Application scenario: Business sharing sensitive files via Paperless-ngx without VPNs.

Operational example: Invalid NextCloud share returns 404, denying access; valid one proxies with cookie.

Bullets:

  • No IP whitelisting.
  • Valid shares only.
  • Rate limiting.
  • Session management.
  • Private network isolation.

Author’s reflection: Security models like this remind me that relying on service-generated secure URLs is crucial, as weak links can undermine the system.

Quick Start Guide for Sneak Link

To get started, generate a signing key, run the Docker image with service URLs and the key, then configure a reverse proxy for HTTPS. Prerequisites include services on private network, domain with split-brain DNS, and Docker.

Summary: Provides a straightforward guide to deploying Sneak Link via Docker.

Central question: “How do I quickly set up and run Sneak Link?”

  1. Generate key: SIGNING_KEY=$(pwgen -n 32 1)
  2. Run Docker: Specify URLs, key, ports, volumes.
  3. Proxy: Forward HTTPS to 8080.

Code block:

docker run -d \
  --name sneak-link \
  -p 8080:8080 \
  -p 9090:9090 \
  -p 3000:3000 \
  -v sneak-link-data:/data \
  -e NEXTCLOUD_URL=https://nextcloud.yourdomain.com \
  -e IMMICH_URL=https://immich.yourdomain.com \
  -e PAPERLESS_URL=https://paperless.yourdomain.com \
  -e PHOTOPRISM_URL=https://photoprism.yourdomain.com \
  -e SIGNING_KEY=$SIGNING_KEY \
  ghcr.io/felixandersen/sneak-link:latest

Application scenario: Initial home server setup for photo sharing.

Operational example: After run, test with a share link; dashboard at port 3000 confirms operation.

Author’s reflection: Quick starts like this have shown me how Docker simplifies deployment, reducing barriers for adopters.

Note: Use reverse proxy for HTTPS; internal proxy is HTTP.

Configuration Options in Sneak Link

Sneak Link is configured via environment variables for service URLs, signing key, ports, cookie age, rate limits, log level, and more. At least one service URL is required.

Summary: Covers all configurable aspects to customize Sneak Link.

Central question: “How can I configure Sneak Link to fit my setup?”

Table of variables:

Variable Required Default Description
NEXTCLOUD_URL No* – NextCloud instance URL
IMMICH_URL No* – Immich instance URL
PAPERLESS_URL No* – Paperless-ngx instance URL
PHOTOPRISM_URL No* – Photoprism instance URL
SIGNING_KEY Yes – Secret key for signing authentication tokens
LISTEN_PORT No 8080 Port for the HTTP server
COOKIE_MAX_AGE No 86400 Cookie expiration time in seconds
RATE_LIMIT_REQUESTS No 10 Maximum requests per IP per window
RATE_LIMIT_WINDOW No 300 Rate limiting window in seconds
LOG_LEVEL No info Log level (debug, info, warn, error)
METRICS_PORT No 9090 Port for Prometheus metrics endpoint
DASHBOARD_PORT No 3000 Port for web dashboard
DB_PATH No /data/sneak-link.db SQLite database path for metrics storage
METRICS_RETENTION_DAYS No 30 Data retention period in days

*At least one service URL must be configured.

Application scenario: Adjusting rate limits for high-traffic sharing.

Operational example: Set COOKIE_MAX_AGE=172800 for two-day sessions in Docker env.

Endpoints: Dashboard at :3000, metrics at :9090/metrics, health at :9090/health.

Author’s reflection: Configurability via env vars has proven efficient, allowing fine-tuning without code changes.

Security Considerations for Using Sneak Link

Use Sneak Link at your discretion as it’s new software; it relies on secure share URLs, has IP-based rate limiting that can be bypassed, no automatic session invalidation, uses cookies with privacy implications, and logs IPs. Implement additional protections as needed.

Summary: Discusses potential risks and best practices for secure deployment.

Central question: “What security considerations should I keep in mind when using Sneak Link?”

Key points:

  • Share URL security depends on service entropy.
  • Rate limiting: Add proxy-level defenses.
  • Session: Cookies persist post-deletion.
  • Cookie compliance: Consider privacy laws.
  • Logging: Manage retention policies.

Application scenario: Public deployment for business; ensure GDPR compliance for cookies.

Operational example: If shares are deleted in NextCloud, active cookies still grant access until expiration.

Author’s reflection: New tools like this highlight the need for caution, teaching me to always layer defenses.

Logging in Sneak Link

Sneak Link outputs structured JSON logs for access (HTTP requests), security (events like rate limits), and validation (share checks). Logs include level, message, time, type, and details.

Summary: Explains the logging system for tracking operations.

Central question: “How does logging work in Sneak Link and what does it capture?”

Example:

{"level":"info","msg":"HTTP request","time":"2024-01-01T12:00:00Z","type":"access","ip":"1.2.3.4","method":"GET","path":"/s/AbCdEf123","status":200,"duration":45}
{"level":"warn","msg":"Security event","time":"2024-01-01T12:00:01Z","type":"security","event":"rate_limit_exceeded","ip":"1.2.3.4","details":"requests: 11, window: 5m0s"}

Application scenario: Debugging unauthorized access attempts.

Operational example: Review logs for “security” type to spot exceeded limits.

Author’s reflection: Structured logs have made troubleshooting intuitive, a valuable insight for maintainability.

Conclusion

Sneak Link simplifies secure sharing from self-hosted services by combining access control with observability, all in a lightweight package. Its focus on URL validation, proxying, and monitoring addresses common pain points in self-hosting, making it a practical choice for technical users seeking balance between security and accessibility.

Author’s final reflection: Working with concepts in Sneak Link reinforces that open-source tools thrive on community feedback, encouraging careful adoption and contributions for maturity.

To enhance understanding, here’s a relevant image of a secure network setup.

Secure Network Illustration
Image source: Unsplash.

Action Checklist / Implementation Steps

  1. Verify prerequisites: Services running privately, domain with split-brain DNS, Docker installed.
  2. Generate signing key using pwgen.
  3. Configure environment variables for services and settings.
  4. Run Docker container with ports and volumes.
  5. Set up reverse proxy for HTTPS to port 8080.
  6. Test with a share link; monitor via dashboard.
  7. Adjust configs like rate limits as needed.
  8. Review logs and metrics regularly.

One-page Overview

Sneak Link is an open-source tool for secure link-based access to self-hosted services like NextCloud, Immich, Paperless-ngx, and Photoprism. It uses URL-knocking for validation, issues cookies for access, and includes rate limiting without IP whitelisting. Key features: Observability via dashboard, Prometheus metrics, SQLite historical data. Setup: Docker with env vars for URLs, key, ports. Security: Relies on strong share URLs, logs events. Flow: Create shares, send links, validate internally, proxy if valid. Benefits: Private services, easy external sharing. Considerations: New software, add layers for protection.

FAQ

Q: What services does Sneak Link support?
A: It supports NextCloud, Immich, Paperless-ngx, and Photoprism, with an extensible architecture.

Q: Do I need to expose my services to the internet?
A: No, services stay on private networks; Sneak Link proxies valid requests.

Q: How does validation work?
A: It checks the internal service for HTTP 200 on the share path; 404 or 401 denies access.

Q: What happens if rate limits are exceeded?
A: Access is denied, and the event is logged as a security incident.

Q: Can I customize cookie expiration?
A: Yes, via the COOKIE_MAX_AGE environment variable in seconds.

Q: How do I access the dashboard?
A: At http://your-host:3000/, showing metrics and sessions.

Q: Is HTTPS required?
A: Sneak Link uses HTTP internally; use a reverse proxy for HTTPS termination.

Q: What data is stored in the database?
A: Historical metrics and analytics, retained for 30 days by default.