Capturing authentication traffic using cirrus‐scope - himmelblau-idm/himmelblau GitHub Wiki
Capturing OAuth2 traffic when authenticating to Azure Entra ID is essential for debugging and resolving issues in the libhimmelblau
library. By inspecting the detailed HTTP requests and responses exchanged during the authentication process, developers can identify discrepancies, such as malformed requests, unexpected status codes, or incorrect parameters. This comprehensive view helps pinpoint where errors occur, enabling targeted fixes and enhancements to improve the reliability and functionality of Himmelblau, ultimately leading to smoother integrations and user experiences.
This guide walks you through how to capture and inspect authentication traffic using the
cirrus-scope
diagnostic tool along withmitmproxy
.
New:
cirrus-scope
now includes anobfuscate
command to help automatically mask sensitive data from these captures before sharing them.
Step-by-Step Instructions
You’ll learn how to capture traffic, then obfuscate sensitive details using cirrus-scope obfuscate
.
-
Download
cirrus-scope
:Prebuilt binaries are available from the official Himmelblau downloads page:
-
Download
mitmproxy
:Download
mitmproxy
from their website, and extract the binaries.tar -xf mitmproxy-11.0.0-linux-x86_64.tar.gz
-
Start
mitmweb
:Run the following command to start
mitmweb
:./mitmweb
This starts
mitmweb
and opens a web interface for monitoring HTTP and HTTPS traffic. -
Install the mitmproxy CA Certificate:
On Ubuntu,
sudo cp $HOME/.mitmproxy/mitmproxy-ca-cert.pem /usr/local/share/ca-certificates/mitmproxy.crt sudo update-ca-certificates
Or on Fedora,
sudo cp $HOME/.mitmproxy/mitmproxy-ca-cert.pem /etc/pki/ca-trust/source/anchors/ sudo update-ca-trust
Or on openSUSE Leap,
sudo cp $HOME/.mitmproxy/mitmproxy-ca-cert.pem /usr/share/pki/trust/anchors/mitmproxy.crt sudo update-ca-certificates
-
Access the Web Interface:
Open your web browser and go to:
http://127.0.0.1:8081/
You should see the
mitmweb
dashboard for viewing captured traffic. -
Run
cirrus-scope
with Proxy Enabled:Run the desired test command from
cirrus-scope
, routing its traffic throughmitmproxy
by setting theHTTPS_PROXY
environment variable.Example:
HTTPS_PROXY=http://127.0.0.1:8080 cirrus-scope auth-test --name [email protected]
You will be prompted to enter credentials interactively. You can add
--debug
for detailed logs:HTTPS_PROXY=http://127.0.0.1:8080 cirrus-scope auth-test --name [email protected] --debug
Other available test commands include:
enrollment-test
: Simulates device enrollmentrefresh-token-acquire
: Acquires new access tokens using a refresh tokenprovision-hello-key-test
: Tests Hello for Business key provisioning
-
Capture and Save the HAR File:
- Go to the
mitmweb
dashboard in your web browser. - Click on the "File" drop down menu, then "Save".
- Your browser will download a file called 'flows'
- Go to the
-
Obfuscate the capture using
cirrus-scope
:To help protect sensitive information, run the built-in obfuscator on your captured flows file. This will automatically replace known tokens (like JWTs, Kerberos tickets, flow tokens, request blobs, and your tenant ID) with equal-length asterisk sequences so that the file remains structurally valid.
Example:
cirrus-scope obfuscate -i flows -o flows.obfuscated
You can also specify explicit secrets to obfuscate using the --custom
option, for example:
```bash
cirrus-scope obfuscate -i flows -o flows.obfuscated \
--custom "[email protected]" \
--custom "SuperSecretPassword"
```
This ensures additional sensitive data like emails or passwords are masked. The resulting file flows.obfuscated
will be safe to share for debugging, while still maintaining the exact format required for tools like mitmproxy.
That's it! You have now captured, obfuscated, and saved HTTP(S) traffic as a HAR file.
Important:
Always use cirrus-scope obfuscate
to sanitize your capture. Manually editing the file to remove secrets can corrupt the format, making it unreadable by mitmproxy or other tools. This tool replaces sensitive data with exact-length values to keep the file structurally valid.
It remains your responsibility to review the file to ensure no secrets remain. Passwords and plaintext credentials are not detected automatically — always provide them explicitly via --custom
if needed.