Skip to main content

Troubleshooting

Having issues with SAT? This guide will help you resolve common problems. Click on any issue below to see the solution.

Diagnostic Notebooks​

Quick Diagnosis

Diagnosis notebooks for each cloud platform are available to help troubleshoot your SAT setup.

To run the appropriate diagnostic notebook:

  1. Navigate to Workspace → Applications → SAT → files → notebooks → diagnosis folder
  2. Open and run the notebook corresponding to your cloud provider

Available diagnostic notebooks:

Common Issues​

Error:

Secret does not exist with scope: sat_scope and key: sat_tokens

Resolution:

Check if the tokens are configured with the correct names by listing and comparing with the configuration.

databricks --profile e2-sat secrets list-secrets sat_scope

Error:

Traceback (most recent call last): 
File "/databricks/python/lib/python3.8/site-packages/urllib3/connectionpool.py", line 670, in urlopen  
httplib_response = self._make_request(  
File "/databricks/python/lib/python3.8/site-packages/urllib3/connectionpool.py", line 381, in _make_request  
self._validate_conn(conn)  
File "/databricks/python/lib/python3.8/site-packages/urllib3/connectionpool.py", line 978, in _validate_conn  
conn.connect()  
File "/databricks/python/lib/python3.8/site-packages/urllib3/connection.py", line 362, in connect  
self.sock = ssl_wrap_socket(  
File "/databricks/python/lib/python3.8/site-packages/urllib3/util/ssl_.py", line 386, in ssl_wrap_socket  
return context.wrap_socket(sock, server_hostname=server_hostname)  
File "/usr/lib/python3.8/ssl.py", line 500, in wrap_socket  
return self.sslsocket_class._create(  
File "/usr/lib/python3.8/ssl.py", line 1040, in _create  
self.do_handshake()  
File "/usr/lib/python3.8/ssl.py", line 1309, in do_handshake  
self._sslobj.do_handshake() 
ConnectionResetError: [Errno 104] Connection reset by peer 
During handling of the above exception, another exception occurred:

Resolution:

Run the following command in your notebook to test connectivity:

%sh 
curl -X GET -H "Authorization: Basic /<base64 of userid:password/>" -H "Content-Type: application/json" https://accounts.cloud.databricks.com/api/2.0/accounts/<account_id>/workspaces

or

%sh 
curl -u 'user:password' -X GET "Content-Type: application/json" https://accounts.cloud.databricks.com/api/2.0/accounts/<account_id>/workspaces

If you don't see a JSON with a clean listing of workspaces, you are likely having a firewall issue that is blocking calls to the accounts console. Please have your infrastructure team add accounts.cloud.databricks.com to the allow-list. Ensure that the private IPv4 address from the NAT gateway is added to the IP allow list.

The Permissions Analysis app uses on-behalf-of-user (OBO) authentication in 0.8.0. The required sql scope is declared in the SAT install templates, but each user must consent to the scope on first open after the upgrade. If you opened the app before upgrading, your browser session has a cached consent grant without sql and you'll see the banner.

Resolution (try in order):

  1. Open the app URL in a private/incognito window — this triggers a fresh consent prompt.
  2. Or clear cookies for the workspace domain in your regular browser, then reopen the app.
  3. Or revoke the prior authorization from your account profile (if your workspace exposes a "Linked apps" list), then reopen.

The full background and permanent setup is on the Permissions Analysis page.

In 0.8.0 the app runs Statement Execution as the calling user, so Unity Catalog enforces the user's grants on the Permissions Analysis tables. If the user does not have SELECT on those tables, the app renders a friendly banner instead of a SQL error.

Resolution: an admin grants SELECT on the three tables to the user or group that needs to use the app. Replace <catalog> and <schema> with the values used during your SAT install:

GRANT SELECT ON TABLE `<catalog>`.`<schema>`.brickhound_vertices             TO `<admin_group>`;
GRANT SELECT ON TABLE `<catalog>`.`<schema>`.brickhound_edges                TO `<admin_group>`;
GRANT SELECT ON TABLE `<catalog>`.`<schema>`.brickhound_collection_metadata  TO `<admin_group>`;

NS-14 is a live behavior check — it runs from the SAT driver compute and probes a small list of public destinations to confirm whether outbound traffic is reachable. On a properly egress-restricted network the probes are expected to fail, and that's the pass state for the check: egress controls are doing their job.

If you see NS-14 reporting "egress blocked" on a workspace where you've configured network policies or firewall rules to restrict outbound traffic, no action is required.

If your workspace does not have access to PyPI, follow these steps to install the required libraries manually:

Steps:

  1. Download the dbl_sat_sdk version specified in the notebook notebooks/utils/initialize from PyPi:

    https://pypi.org/project/dbl-sat-sdk/

  2. Upload the dbl_sat_sdk-w.x.y-py3-none-any.whl to a dbfs location. You can use the databricks-cli as one mechanism to upload. For example:

    databricks --profile e2-satfs cp /localdrive/whlfile/dbl_sat_sdk-w.x.y-py3-none-any.whl dbfs:/FileStore/wheels/

  3. Additionally, download the following wheel files and upload them to the dbfs location as above:

    https://github.com/databricks-industry-solutions/security-analysis-tool/tree/main/docs/wheels

  4. Upload all wheel files to /FileStore/wheels in your workspace.

  5. Verify all files are there by running:

    %fs ls /FileStore/wheels

  6. Then change the cell in your notebook install_sat_sdk to this:

    %pip install msal --find-links /Volumes/{catalog}/{schema}/{volume_name}/msal-1.22.0-py2.py3-none-any.whl

    %pip install dbl-sat-sdk==0.1.37 --find-links /Volumes/{catalog}/{schema}/{volume_name}/dbl_sat_sdk-0.1.37-py3-none-any.whl

  7. Make sure the versions for the above libraries match.