Go-based tooling to manipulate (e.g., normalize/decode) Microsoft Office 365 "Safe Links" URLs.
- Project home
- Overview
- Features
- Changelog
- Requirements
- Installation
- Configuration
- Examples
- License
- References
See our GitHub repo for the latest code, to file an issue or submit improvements for review and potential inclusion into the project.
This repo is intended to provide various tools used to manipulate (e.g., normalize/decode) Microsoft Office 365 "Safe Links" URLs.
Tool Name | Overall Status | Description |
---|---|---|
usl |
🆗Beta | Small CLI tool for decoding a given Safe Links URL. |
dsl |
💥Alpha | Small CLI tool for decoding Safe Links URLs within input text. |
dslg |
💥Alpha | GUI tool for decoding Safe Links URLs within input text. |
eslg |
💥Alpha | GUI tool for encoding normal URLs within input text for testing purposes. |
Small CLI tool for decoding a given Safe Links URL.
- Specify single Safe Links URL
- via positional argument
- via flag
- via interactive prompt
- Specify multiple bare Safe Links URLs (no surrounding text)
- via interactive prompt
- via standard input ("piping")
- via file (using flag)
- Optional verbose listing of query parameter values within a given Safe Links URL.
Small CLI tool for decoding Safe Links URLs within surrounding input text.
- Specify single Safe Links URL
- via positional argument
- via flag
- via interactive prompt
- Specify multiple Safe Links URLs (with surrounding text untouched)
- via interactive prompt
- via standard input ("piping")
- via file (using flag)
GUI tool for decoding Safe Links URLs within given input text.
- Specify single Safe Links URL
- Specify multiple Safe Links URLs (with surrounding text untouched)
GUI tool for generating test data.
See the CHANGELOG.md
file for the changes associated with
each release of this application. Changes that have been merged to master
,
but not yet an official release may also be noted in the file under the
Unreleased
section. A helpful link to the Git commit history since the last
official release is also provided for further review.
The following is a loose guideline. Other combinations of Go and operating systems for building and running tools from this repo may work, but have not been tested.
- Go
- see this project's
go.mod
file for preferred version - this project tests against officially supported Go
releases
- the most recent stable release (aka, "stable")
- the prior, but still supported release (aka, "oldstable")
- see this project's
- GCC
- if building with custom options (as the provided
Makefile
does)
- if building with custom options (as the provided
- mingw-w64
- if building GUI app(s) for Windows
- used to perform CGO-enabled builds of Fyne (GUI) applications
make
- if using the provided
Makefile
- if using the provided
- Fyle toolkit OS dependencies
- see https://docs.fyne.io/started/ for OS-specific packages
Tip
Use make docker-release-build
or podman-release-build
Makefile recipes to generate/use build containers compatible with this project.
The CLI apps are broadly compatible but have been tested against:
- Microsoft Windows 10
- Ubuntu 20.04
The GUI app(s) have been tested against:
- Microsoft Windows 10
- Microsoft Windows 11
- Ubuntu 20.04
libgl1
package was needed
Note
The build image used by this project has an inherited dependency on the official upstream Go Docker image and shares that image's minimum glibc version requirement.
As of this writing, a glibc release of version 2.31 or newer is required to match the Debian 11 base image used by current Go Docker images. Ubuntu 20.04 has glibc 2.31 and meets this requirement. Older distro versions may not meet this requirement and will require building from source.
Important
When the upstream Go Docker image swaps out the minimum Debian base image OS (currently Debian 11) this may also mean dropping support for some Linux distros.
Tip
Use docker-release-build
or podman-release-build
Makefile recipes to use build containers compatible with this project.
- Download Go
- Install Go
- Clone the repo
cd /tmp
git clone https://github.com/atc0005/safelinks
cd safelinks
- Install dependencies (optional)
- for Ubuntu Linux
- if building for the current architecture
sudo apt-get install make gcc xz-utils libgl1-mesa-dev xorg-dev
- if building x86 binaries on x64 OS
sudo dpkg --add-architecture i386
sudo dpkg --configure -a
sudo apt-get update
sudo apt-get install make bsdmainutils gcc gcc-multilib gcc-mingw-w64 xz-utils libgl1-mesa-dev xorg-dev
sudo apt-get install libxinerama-dev:i386 libgl1-mesa-dev:i386 libxrandr-dev:i386 libxxf86vm-dev:i386 libxi-dev:i386 libxcursor-dev:i386
- if building for the current architecture
- for CentOS Linux
sudo yum install make gcc libXcursor-devel libXrandr-devel mesa-libGL-devel libXi-devel libXinerama-devel libXxf86vm-devel
- for Ubuntu Linux
- Build
- for the detected current operating system and architecture, explicitly
using bundled dependencies in top-level
vendor
folder- most likely this is what you want (if building manually)
go build -mod=vendor ./cmd/usl/
go build -mod=vendor ./cmd/dsl/
go build -mod=vendor ./cmd/dslg/
go build -mod=vendor ./cmd/eslg/
- manually, explicitly specifying target OS and architecture
GOOS=linux GOARCH=amd64 go build -mod=vendor ./cmd/usl/
- substitute
GOARCH=amd64
with the appropriate architecture if using different hardware (e.g.,GOARCH=arm64
orGOARCH=386
) - substitute
GOOS=linux
with the appropriate OS if using a different platform (e.g.,GOOS=windows
)
- substitute
GOOS=linux GOARCH=amd64 go build -mod=vendor ./cmd/dsl/
GOOS=linux GOARCH=amd64 go build -mod=vendor ./cmd/dslg/
GOOS=linux GOARCH=amd64 go build -mod=vendor ./cmd/eslg/
- using Makefile
all
recipemake all
- generates x86 and x64 binaries
- using Makefile
release-build
recipemake release-build
- generates the same release assets as provided by this project's releases
- for the detected current operating system and architecture, explicitly
using bundled dependencies in top-level
- Locate generated binaries
- if using
Makefile
- look in
/tmp/safelinks/release_assets/usl/
- look in
/tmp/safelinks/release_assets/dsl/
- look in
/tmp/safelinks/release_assets/dslg/
- look in
/tmp/safelinks/release_assets/eslg/
- look in
- if using
go build
- look in
/tmp/safelinks/
- look in
- if using
- Copy the applicable binaries to whatever systems needs to run them so that they can be deployed
Note
Depending on which Makefile
recipe you use the generated binary may be compressed and have an xz
extension. If so, you should decompress the binary first before deploying it (e.g., xz -d usl-linux-amd64.xz
).
- Download the latest release binaries
- Decompress binaries
- e.g.,
xz -d usl-linux-amd64.xz
- 7-Zip also works well for this on Windows systems (e.g., for systems without Git for Windows or WSL)
- e.g.,
- Copy the applicable binaries to whatever systems needs to run them so that they can be deployed
NOTE:
DEB and RPM packages are provided as an alternative to manually deploying binaries.
- Place
usl
in a location where it can be easily accessed - Place
dsl
in a location where it can be easily accessed - Place
dslg
in a location where it can be easily accessed - Place
eslg
in a location where it can be easily accessed
Note
The libgl1
package is needed on target Ubuntu systems for the dslg
and eslg
apps.
- Use the
-h
or--help
flag to display current usage information. - Flags marked as
required
must be set via CLI flag. - Flags not marked as required are for settings where a useful default is already defined, but may be overridden if desired.
Note
🛠️ The dsl
tool does not support CLI arguments but may do so in the
future.
Flag | Required | Default | Repeat | Possible | Description |
---|---|---|---|---|---|
h , help |
No | false |
No | h , help |
Show Help text along with the list of supported flags. |
version |
No | false |
No | version |
Whether to display application version and then immediately exit application. |
v , verbose |
No | false |
No | v , verbose |
Display additional information about a given Safe Links URL. |
u , url |
maybe | No | u , url |
Safe Links URL to decode | |
f , inputfile |
maybe | No | valid path to file | Path to file containing Safe Links URLs to decode |
NOTE: If an input url
is not specified (e.g., via flag, positional argument
or standard input) a prompt is provided to enter a Safe Links URL.
A URL pattern is accepted as a single positional argument in place of the u
or url
flag. It is recommended that you quote the URL pattern to help
prevent some of the characters from being interpreted as shell commands (e.g.,
&
as an attempt to background a command).
One or more URL patterns can be provided by piping them to the usl
tool.
An attempt is made to decode all input URLs (no early exit). Successful
decoding results are emitted to stdout
with decoding failures emitted to
stderr
. This allows for splitting success results and error output across
different files (e.g., for later review).
The usl
tool can also be called without any input (e.g., flags, positional
argument, standard input). In this scenario it will prompt you to insert/paste
the URL pattern (quoted or otherwise).
Important
This tool is in early development and behavior is subject to change.
Note
🛠️ This feature is not implemented but may be added in the future.
Note
🛠️ This feature is not implemented but may be added in the future.
Text with interspersed URLs (separated by whitespace) can be provided for
decoding by piping it to the dsl
tool. Output is sent to stdout
.
Each matched Safe Links URL is replaced with a decoded version leaving surrounding text as-is.
The dsl
tool can also be called without any input. In this scenario it will
prompt you to insert/paste content for decoding.
If no input is provided for a the listed amount of time the dsl
tool will
timeout and exit.
No command-line arguments are currently supported.
No command-line arguments are currently supported.
Though probably not required for all terminals, we quote the Safe Links URL to prevent unintended interpretation of characters in the URL.
$ usl 'SafeLinksURLHere'
https://go.dev/dl/
$ usl --url 'SafeLinksURLHere'
https://go.dev/dl/
In this example we just press enter so that we will be prompted for the input URL pattern.
$ usl
Enter URL: SafeLinksURLHere
https://go.dev/dl/
$ cat file.with.links | usl
https://go.dev/dl/
https://example.com
https://example.net
$ echo 'SafeLinksURLHere' | usl
https://go.dev/dl/
$ usl --filename file.with.links
https://go.dev/dl/
https://example.com
https://example.net
$ usl --verbose --url 'SafeLinksURLHere'
Expanded values from the given link:
data : PLACEHOLDER
host : nam99.safelinks.protection.outlook.com
reserved : 0
sdata : PLACEHOLDER
url : https://go.dev/dl/
Note
🛠️ This feature is not implemented but may be added in the future.
Note
🛠️ This feature is not implemented but may be added in the future.
In this example we just press enter so that we will be prompted for the input URL pattern.
$ dsl
Enter single or multi-line input. Press Ctrl-C to stop (or wait 15s for timeout).
- Feedback from this app is sent to stderr.
- Decoding results are sent to stdout.
- Tip: Redirect stdout to a file for multiple input lines.
Not shown is the copy/pasted content with Safe Links encoded URLs interspersed (e.g., right-click pasted into console).
$ cat file.with.mixed.text.content | dsl
tacos are great https://go.dev/dl/ but so are cookies https://example.com
$ echo 'SafeLinksURLHere' | dsl
https://go.dev/dl/
$ dsl < file.with.mixed.text.content > decoded-output.txt
tacos are great https://go.dev/dl/ but so are cookies https://example.com
Note
🛠️ This feature is not implemented but may be added in the future.
- Launch application
- Copy single URL or mix of URLs and text (e.g., copying an email) into the input field
- Press
Decode
button - Press
Copy to Clipboard
button - Paste decoded text where needed (e.g., a ticket)
Warning
The Copy to Clipboard
action does not preserve any existing clipboard content; there is no undo for using this button
- Launch application
- Copy single unencoded URL or mix of unencoded URLs and text (e.g., copying an email) into the input field
- Press one of the desired "action" buttons
Encode All
Encode Randomly
QueryEscape All
QueryEscape Randomly
- Press
Copy to Clipboard
button - Paste transformed text where needed (e.g., a new
testdata
file)
Warning
The Copy to Clipboard
action does not preserve any existing clipboard content; there is no undo for using this button
See the LICENSE file for details.
- https://learn.microsoft.com/en-us/microsoft-365/security/office-365-security/safe-links-about
- https://learn.microsoft.com/en-us/training/modules/manage-safe-links/
- https://security.stackexchange.com/questions/230309/is-a-safelinks-protection-outlook-com-link-phishing
- https://techcommunity.microsoft.com/t5/security-compliance-and-identity/data-sdata-and-reserved-parameters-in-office-atp-safelinks/td-p/1637050
The following *.safelinks.protection.outlook.com
subdomains have been found
listed on various KB articles and forums:
emea01
eur04
na01
nam01
nam02
nam04
nam10
nam11
nam12
The following alternative tools were encountered while researching valid Safe Links subdomains. These tools are listed here for informational purposes; no endorsement is implied.
Important
No guarantees are made regarding the functionality or privacy policies of the following online or local tools. YMMV.
Online decoders:
- https://safelinks.apps.buffalo.edu/
- https://digital.va.gov/employee-resource-center/safe-link-decoder/
- https://wmich.edu/oit/converter/
- https://it.cornell.edu/decode
- https://www.ohio.edu/oit/security/safe-computing/identifying-malicious-email/safelinks-decoder
- https://www.umsystem.edu/forms/safe-link-decoder
- https://stockton.edu/omni-cms-support/safelinks-decoder.html
- https://infosecurity.utdallas.edu/safelink/
Local decoders: