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 monitor processes.
Tool Name | Overall Status | Description |
---|---|---|
usl |
Alpha | Small CLI tool for decoding a given Safe Links URL. |
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 Safe Links URLs
- via standard input ("piping")
- via file (using flag)
- Optional verbose listing of query parameter values within a given Safe Links URL.
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
make
- if using the provided
Makefile
- if using the provided
- Microsoft Windows 10
- Ubuntu 20.04
- Download Go
- Install Go
- Clone the repo
cd /tmp
git clone https://github.com/atc0005/safelinks
cd safelinks
- Install dependencies (optional)
- for Ubuntu Linux
sudo apt-get install make gcc
- for CentOS Linux
sudo yum install make gcc
- for Ubuntu Linux
- Build
- manually, explicitly specifying target OS and architecture
GOOS=linux GOARCH=amd64 go build -mod=vendor ./cmd/usl/
- most likely this is what you want (if building manually)
- substitute
amd64
with the appropriate architecture if using different hardware (e.g.,arm64
or386
)
- 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
- manually, explicitly specifying target OS and architecture
- Locate generated binaries
- if using
Makefile
- look in
/tmp/safelinks/release_assets/usl/
- 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
- 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.
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 URL 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).
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/
http://example.com
http://example.net
$ echo 'SafeLinksURLHere' | usl
https://go.dev/dl/
$ usl --filename file.with.links
https://go.dev/dl/
http://example.com
http://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/
See the LICENSE file for details.
- https://learn.microsoft.com/en-us/microsoft-365/security/office-365-security/safe-links-about
- 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