{"id":19467901,"url":"https://github.com/secret-guest/windows_link_reader","last_synced_at":"2026-04-04T14:04:07.823Z","repository":{"id":196242227,"uuid":"695600367","full_name":"SECRET-GUEST/windows_link_reader","owner":"SECRET-GUEST","description":"Enable compatibility for Windows shortcut (.lnk) files on Linux and macOS.","archived":false,"fork":false,"pushed_at":"2026-04-01T09:34:50.000Z","size":267,"stargazers_count":10,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-01T11:35:26.957Z","etag":null,"topics":["c","compatibility","linux","lnk","lnk-builder","lnk-exploit","lnk-files","lnk-shortcut","lnkcapture","macos","shortcut-files","tool","windows"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SECRET-GUEST.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-09-23T16:57:57.000Z","updated_at":"2026-04-01T09:34:54.000Z","dependencies_parsed_at":"2025-12-31T21:00:52.828Z","dependency_job_id":null,"html_url":"https://github.com/SECRET-GUEST/windows_link_reader","commit_stats":{"total_commits":37,"total_committers":1,"mean_commits":37.0,"dds":0.0,"last_synced_commit":"65aa5500da545f2bd5d203d0783854cb3884fc39"},"previous_names":["secret-guest/windows_link_reader"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/SECRET-GUEST/windows_link_reader","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SECRET-GUEST%2Fwindows_link_reader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SECRET-GUEST%2Fwindows_link_reader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SECRET-GUEST%2Fwindows_link_reader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SECRET-GUEST%2Fwindows_link_reader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SECRET-GUEST","download_url":"https://codeload.github.com/SECRET-GUEST/windows_link_reader/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SECRET-GUEST%2Fwindows_link_reader/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31402277,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c","compatibility","linux","lnk","lnk-builder","lnk-exploit","lnk-files","lnk-shortcut","lnkcapture","macos","shortcut-files","tool","windows"],"created_at":"2024-11-10T18:37:20.137Z","updated_at":"2026-04-04T14:04:07.814Z","avatar_url":"https://github.com/SECRET-GUEST.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"![C](https://img.shields.io/badge/C-GCC-purple)\n![Version](https://img.shields.io/badge/LINUX-yellow) ![Version](https://img.shields.io/badge/MacOS-white) \n```\n██╗     ███╗   ██╗██╗  ██╗    ██████╗ ███████╗ █████╗ ██████╗ ███████╗██████╗ \n██║     ████╗  ██║██║ ██╔╝    ██╔══██╗██╔════╝██╔══██╗██╔══██╗██╔════╝██╔══██╗\n██║     ██╔██╗ ██║█████╔╝     ██████╔╝█████╗  ███████║██║  ██║█████╗  ██████╔╝\n██║     ██║╚██╗██║██╔═██╗     ██╔══██╗██╔══╝  ██╔══██║██║  ██║██╔══╝  ██╔══██╗\n███████╗██║ ╚████║██║  ██╗    ██║  ██║███████╗██║  ██║██████╔╝███████╗██║  ██║\n╚══════╝╚═╝  ╚═══╝╚═╝  ╚═╝    ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚═════╝ ╚══════╝╚═╝  ╚═╝\n                                                                              \n```\n\n# LNK Reader 🖥️\n\n**open_lnk** is a lightweight desktop utility that opens Windows `.lnk` (Shell Link) shortcut files directly on Linux (and macOS).\n\nIt is designed first and foremost for **double-click / “Open with” usage**, not for manual command-line interaction.\n\nThe goal is simple:\n👉 *You double-click a `.lnk` file, it opens the correct target — even if it lives on a different drive, partition, or network share.*\n\n---\n\n## 📚 Table of Contents\n\n* [Overview](#lnk-reader-️)\n* [How it works](#-how-it-works-high-level)\n* [Key Features](#-key-features)\n* [Prerequisites](#-prerequisites)\n* [Installation](#-installation)\n* [Uninstall](#-uninstall)\n* [Usage](#-usage)\n* [Configuration files](#️-configuration-files)\n* [Limitations](#-limitations)\n* [License](#-license)\n* [Support](#-support)\n\n---\n\n## 🧠 How it works (high level)\n\nWhen a `.lnk` file is opened, `open_lnk`:\n\n1. Parses the Windows **Shell Link** binary format (subset of the official Microsoft specification).\n2. Extracts the most reliable target path from the available fields.\n3. Translates Windows paths to Linux/macOS equivalents:\n\n   * Drive letters (`X:\\...`)\n   * UNC paths (`\\\\server\\share\\...`)\n4. Tries multiple resolution strategies automatically.\n5. Opens the resolved path or network URI using the system default handler.\n\nIf the target **cannot be resolved automatically**, a **graphical assistant** is shown to help the user select the correct mount point, and the choice is remembered for next time.\n\n[Demo video](https://github.com/SECRET-GUEST/windows_link_reader/assets/92639080/f92222d6-e028-4166-8e6d-a9c7bd40f144)\n\n---\n\n## 🌟 Key Features\n\n### Core features\n\n* Parses common Shell Link fields (ANSI + Unicode):\n\n  * `LocalBasePath`, `CommonPathSuffix`, `RelativePath`\n  * `WorkingDir`, `Arguments`, `IconLocation`\n* Full UTF-16LE → UTF-8 conversion (including surrogate pairs)\n* Windows path normalization (`\\` → `/`)\n* Best-effort resolution with safe fallbacks\n* Opens targets via:\n\n  * `xdg-open` (Linux)\n  * `open` (macOS)\n\n---\n\n### Smart path resolution\n\n#### Drive letters (`X:/...`)\n\nResolution order:\n\n1. **Per-link cache** (exact `.lnk` → mount prefix association)\n2. User mapping file (`mappings.conf`)\n3. Automatic mount probing (`/proc/mounts`, scored)\n4. **Graphical assistant** (if still unresolved)\n\n#### UNC paths (`//server/share/...`)\n\nResolution order:\n\n1. User mapping file\n2. GVFS mounts (GNOME)\n3. CIFS mounts (`/proc/mounts`)\n4. Fallback to `smb://` URI (percent-encoded)\n\n---\n\n### 🧠 Intelligent per-link cache\n\nWhen a `.lnk` cannot be resolved automatically:\n\n* A **GUI dialog** lists currently mounted locations\n* The user selects the correct mount point (or uses a folder chooser)\n* If the merged preview exists, `open_lnk` saves:\n  * A **global mapping rule** (drive letter or UNC share) into `mappings.conf`\n  * A **per-link cache** entry for this specific `.lnk` file\n\nThis means:\n\n* A shortcut pointing to drive **A:** will not interfere with one pointing to **F:**\n* Re-opening the same `.lnk` is instant\n* No global or dangerous assumptions are made\n\nThe cache is stored safely and updated atomically (latest-wins, no duplicates).\nInvalid cache entries are also self-healed automatically:\n\n* entries pointing to the Trash are ignored and removed\n* entries whose rebuilt target no longer exists are removed before the normal resolution flow continues\n* assistant-selected cache entries are only saved after a successful open\n\n---\n\n### 🪟 Graphical assistant (no terminal required)\n\n* Automatically shown **only when resolution fails**\n* Implemented via standard desktop dialogs (`zenity` or compatible tools)\n* Works when launched from:\n\n  * File manager (double-click)\n  * “Open with”\n* No command-line interaction required for normal users\n\n**What it shows (so it’s not a black box):**\n\n* Windows **prefix** (server/share or drive)\n* Windows **suffix**\n* Detected Linux mount points\n* A preview of the final merged path\n  Matching is done on the **prefix only**.\n\n---\n\n### Error handling \u0026 diagnostics\n\n* Clear desktop notifications on failure\n* Safe fallbacks (parent directory, URI)\n* Optional debug output (for developers)\n* GUI runs also write a small log file: `~/.cache/windows-link-reader/open_lnk.log` (or `$XDG_CACHE_HOME/windows-link-reader/open_lnk.log`)\n\n---\n\n## 🔍 Prerequisites\n\n### Build-time\n\n* A C compiler (`gcc` or `clang`)\n* `make`\n\n### Runtime\n\n* Linux: `xdg-open` (from `xdg-utils`)\n* macOS: `open` (built-in)\n\nOptional (recommended on Linux):\n\n* `zenity` or compatible dialog tool (graphical assistant)\n* `notify-send` (desktop notifications)\n\n---\n\n## 📥 Installation\n\n### Convenience installer\n\nYou just have to run:\n\n```bash\n./setup.sh\n```\n\n\n### Alternative manual way : \n\nYou also can run it with make\n\n```bash\nmake\nsudo make install\n```\n\nWhat it does:\n\n* Builds and installs `open_lnk`\n* Installs desktop integration on Linux (desktop entry + icon)\n* On macOS, creates a small Finder wrapper app **Open LNK.app** so you can use *Open With* / double-click (`/Applications` preferred, fallback: `~/Applications`)\n\n---\n\n## 🧹 Uninstall\n\nRun:\n\n```bash\n./uninstall.sh\n```\n\nThis removes:\n\n* `open_lnk` binary (system and user locations)\n* Desktop entries/icons and refreshes caches (Linux, best-effort)\n* macOS wrapper app (`/Applications/Open LNK.app` and `~/Applications/Open LNK.app`) if present\n\nNo reboot required.\n\n---\n\n## ▶️ Usage\n\n**Normal usage (recommended):**\n\n* Double-click a `.lnk` file\n* Or right-click → *Open with* → **LNK Reader** / **Open LNK**\n\n**macOS note:**\n`open_lnk` is a command-line tool. Finder cannot list CLI binaries in *Open With*.\nAfter running `setup.sh`, use the generated **Open LNK.app** wrapper to set it as default handler:\nFinder → Get Info → Open with → **Open LNK** → Change All.\nIf Finder doesn't refresh the list, run: `killall Finder` (or log out/in).\n\n**Simple maintenance command:**\n\n```bash\nopen_lnk --clear-cache\n```\n\nThis removes the per-link cache file and exits without processing any `.lnk`.\n\n---\n\n## ⚙️ Configuration files\n\n### Mapping file (optional)\n\nUsed for global drive / UNC mappings:\n\n```\n~/.config/windows-link-reader/mappings.conf\n```\n\nExample:\n\n```ini\n# Drive letter mapping\nF:=/media/me/F_Daten\nX:=~/nas/Z\nY:=$HOME/nas/Z\nZ:=${HOME}/nas/Z\n\n# UNC mapping\n//server/share=/mnt/share\n//server/share=~/mnt/share\n\\\\share_url.fr\\home\\$USER=$HOME/nas/P\n```\n\nOn the right-hand side only, `open_lnk` supports these limited HOME shortcuts:\n\n* `~`\n* `~/...`\n* `$HOME`\n* `$HOME/...`\n* `${HOME}`\n* `${HOME}/...`\n\nNo other shell expansion is performed.\n\nOn the left-hand side only for UNC rules, `open_lnk` supports these limited USER tokens:\n\n* `$USER`\n* `${USER}`\n\nThese USER tokens are expanded before UNC normalization and matching. No other shell variables or shell syntax are expanded on the UNC side.\n\n### Per-link cache\n\nStored separately and managed automatically:\n\n```text\n~/.cache/windows-link-reader/links.conf\n```\n\nor:\n\n```text\n$XDG_CACHE_HOME/windows-link-reader/links.conf\n```\n\nNotes:\n\n* No manual editing is normally required\n* invalid or suspicious entries are removed automatically\n* `open_lnk --clear-cache` deletes this file if you want a full reset\n\n---\n\n## ⛔ Limitations\n\n* Not a full implementation of every Shell Link feature (some ExtraData blocks are ignored)\n* Resolution is best-effort and depends on available mounts\n* Network shares may still require authentication handled by the OS\n\n---\n\n## ❓ Support\n\nPlease open an issue on GitHub if you encounter a (real) problem or have (a useful) suggestion:\n[https://github.com/SECRET-GUEST/windows_link_reader/issues](https://github.com/SECRET-GUEST/windows_link_reader/issues)\n\n\n```\n     _ ._  _ , _ ._            _ ._  _ , _ ._    _ ._  _ , _ ._      _ ._  _ , _ .__  _ , _ ._   ._  _ , _ ._   _ , _ ._   .---.  _ ._   _ , _ .__  _ , _ ._   ._  _ , _ ._      _ ._  _ , _ .__  _ , _ . .---\u003c__. \\ _\n   (_ ' ( `  )_  .__)        (_ ' ( `  )_  .__ (_ ' ( `  )_  .__)  (_ '    ___   ._( `  )_  .__)  ( `  )_  .__)   )_  .__)/     \\(_ ' (    )_  ._( `  )_  .__)  ( `  )_  .__)  (_ ' ( `  )_  ._( `` )_  . `---._  \\ \\ \\\n ( (  (    )   `)  ) _)    ( (  (    )   `)  ) (  (    )   `)  ) _ (  (   (o o) )     )   `)  ) _    )   `)  ) _    `)  ) \\.@-@./(  (    )   `)     )   `)  ) _    )   `)  ) _ (  (    )   `)         `) ` ),----`- `.))  \n(__ (_   (_ . _) _) ,__)  (__ (_   (_ . _) _) _ (_   (_ . _) _) ,__ (_   (  V  ) _) (_ . _) _) ,_  (_ . _) _) ,_ . _) _) ,/`\\_/`\\ (_   (  . _) _) (_ . _) _) ,_  (_ . _) _) ,__ (_   (_ . _) _) (__. _) _)/ ,--.   )  |\n    `~~`\\ ' . /`~~`           `~~`\\ ' . /`~~`   `~~`\\ ' . /`~~`     `~~`/--m-m- ~~`\\ ' . /`~~`   `\\ ' . /`~~`  `\\ ' . /  //  _  \\\\ ``\\ '  . /`~~`\\ ' . /`~~`   `\\ ' . /`~~`     `~~`\\ ' . /`~~`\\ ' . /`~~/_/    \u003e     |\n         ;   ;                     ;   ;             ;   ;               ;   ;      ;   ;          ;   ;         ;   ;  | \\     )|_   ;    ;      ;   ;          ;   ;               ;   ;      ;   ;    |,\\__-'      |\n         /   \\                     /   \\             /   \\               /   \\      /   \\          /   \\         /   \\ /`\\_`\u003e  \u003c_/ \\  /    \\      /   \\          /   \\               /   \\      /   \\     \\__         \\\n________/_ __ \\___________________/_ __ \\___________/_ __ \\______ __ ___/_ __ \\____/_ __ \\________/_ __ \\_______/_ __ \\\\__/'---'\\__/_/_  __ \\____/_ __ \\________/_ __ \\_____ _______/_ __ \\____/_ __ \\____ __\\___      )\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsecret-guest%2Fwindows_link_reader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsecret-guest%2Fwindows_link_reader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsecret-guest%2Fwindows_link_reader/lists"}