Search with Cypher

Start exploring BloodHound’s prebuilt Cypher queries to uncover relationships and gain deeper insights into your environment.

Purpose

This article describes how to use Cypher queries to extend the basic search functionality of BloodHound. BloodHound offers a variety of prebuilt queries to help you get started. You can search and filter queries by various criteria, create and manage custom queries, and import and export queries in JSON format.

What is Cypher?

Cypher is a query language for graph databases (similar to SQL for relational databases). It uses an ASCII-art style syntax to describe nodes and relationships. If you can describe the path you’re looking for, you can write it in Cypher.

This article provides an introduction to Cypher queries in BloodHound, including how to access prebuilt queries and manage saved queries. See Write Custom Queries for more advanced information.

Quickstart

A great way to start exploring Cypher queries is through the community-driven BloodHound Query Library. This comprehensive collection includes both community-contributed queries and the prebuilt queries that are available in BloodHound.

When you’re ready to explore prebuilt queries inside BloodHound, follow these steps:

1. Open the Saved Queries section

   Click Explore > Cypher > Saved Queries.

   BloodHound displays prebuilt queries by default when you expand the Saved Queries section.

   
2. Select and run a query

   Select a query from the list to display the Cypher syntax and automatically run the query.

   Click the Auto-run selected query checkbox if you prefer to run queries manually.

3. Review the results

   Review the results in the graph view.

   You can modify the Cypher syntax and re-run the query to explore different relationships.

Features

BloodHound provides several features to help you work with Cypher queries. These features enable you to search and manage your queries effectively.

Search and Filter

BloodHound offers several search and filtering options to help you find the right query quickly.

• Search saved queries by name: Quickly locate specific queries using the search text box.

• Filter queries: Narrow down the list of queries by selecting one of the following options:

  • Platforms: Displays queries based on the platform that they target, such as Active Directory or Azure. You can also filter to show only your saved queries.
  • Categories: Displays queries based on logical groups, such as shortest path and dangerous privileges.
  • Source: Displays queries based on their source, such as prebuilt, personal, and shared.

Create and Manage Queries

BloodHound provides several features to help you create and manage custom queries.

For example, you can:

• Save a query: Write a custom query and store it for future use.
• Save As: Create a copy of an existing query with a new name, description, and updated parameters.
• Share a saved query: Share your custom query with all users or specific users in your BloodHound environment.
• Edit a saved query: Modify the Cypher syntax, metadata, and shared access of a custom query.
• Delete saved queries: Remove custom queries that you no longer need.

You can only edit, share, and delete queries that you have created. You cannot modify prebuilt queries directly, but you can use the Save As feature to create a copy that you can then edit.

When you’re ready to create and manage custom queries, follow these steps:

1. Open the query editor

   In the left menu, click Explore > Cypher.

2. Create or copy a query

   Choose one of the following options to create a custom query:

   Create a new custom query

   In the query editor, write a custom query and run it to see the results.

   Copy an existing query

   Select a prebuilt or saved query from the list. Click the drop-down arrow beside Save As to create a copy of the selected query.

3. Enter query details

   In the Save Query dialog, enter a unique name and description for your query.

   
4. Share your query (optional)

   In the Manage Shared Queries dialog, select Set to Public to enable collaboration with all users in your BloodHound environment or select specific users. You can change these settings later if needed.

5. Save your query

   Click Save to store your custom query. It will now appear in the list of saved queries.

6. Edit or delete your query

   To edit or delete your query, click the vertical ellipsis (three dots) next to the query name and select Edit/Share or Delete.

   

Import and Export

BloodHound allows you to import and export queries for easy sharing and backup.

• Import queries from JSON files: Easily add new queries by dragging and dropping JSON files or compressed JSON files into the UI. BloodHound validates the files for correct syntax and notifies you of any errors.
• Export a saved query to a JSON file: Share or back up your queries by exporting them in JSON format. Export is available for saved queries only. You cannot export prebuilt queries directly.

Write Custom Queries

BloodHound lets you run raw Cypher queries directly in the user interface. Use Cypher when you need to inspect relationships, answer targeted questions, or build analyses that go beyond the prebuilt queries.

Cypher supports everything from simple lookups to complex identity attack-path analysis. For example, you can answer questions such as:

• Which users have not reset their passwords in 180 days?
• Which low-privileged users can reach machines that host an unconstrained gMSA?
• What are the shortest paths from low-privilege users to Domain Admins?
• Which objects are in Tier Zero?

For example, use the following query to return all Tier Zero objects:

MATCH (n:Tag_Tier_Zero)
RETURN n

If you need to narrow the results to a specific object type, combine labels in the same pattern. For example, to return only Tier Zero users:

MATCH (n:User:Tag_Tier_Zero)
RETURN n

Do not search for Tier Zero objects by inspecting system_tags properties with patterns such as coalesce(n.system_tags, []). Support for this pattern is temporary and will be deprecated in a future release.

BloodHound represents Tier Zero membership with the Tag_Tier_Zero label, so label matching is the supported and preferred approach.

Elements of the graph database

Everything in the graph database is represented using common terms from graph theory, particularly edges and nodes.

Nodes represent discrete objects in your environment. In BloodHound, a node can represent a user, group, device, repository, or another object collected from a built-in platform or an OpenGraph extension.

Edges represent relationships between nodes and often describe how one object connects to (or can affect) another. In BloodHound, an edge can represent membership, administrative control, trust, or another relationship defined in the graph.

Together, nodes and edges form the paths BloodHound uses to model how access, permissions, and control flow through your environment.

Basic Cypher

Supported Cypher Syntax

When building Cypher queries, it’s important to note that you’re generally trying to build a path using the relationships available to you. Let’s look at an extremely basic query:

MATCH (B)-[A]->(R)
RETURN B

Let’s break down how this Cypher query is constructed. When querying the database, we start our queries with the MATCH keyword. The MATCH clause lets you specify a pattern in the database.

• Each variable in the Cypher query is defined using an identifier, in this case, the following ones: B, A, and R. The identifier for variables can be anything you want, including entire words, such as ‘groups’.
• In Cypher queries, nodes are specified using parentheses, so B and R are nodes in the sample query above.
• Relationships are specified using brackets, so in this example, A represents relationships.

The dashes between the nodes and relationships can be used to specify direction. Relationships in BloodHound always go in the direction of compromise or further privilege, whether through group membership or user credentials from a session.

In the above query, the -> specifies that the query should return relationships that go from B to R. Removing the > will allow the query to search relationships in both directions. Finally, the RETURN statement instructs the database to return the item matched with the corresponding variable name B.

Now, let’s take our previous query and make it a bit more complex:

MATCH (n:User),(m:Group)
MATCH p=(n)-[r:MemberOf*1..3]->(m)
RETURN p

This query is a bit more refined than the previous one. By using labels on both nodes and edges, we can make our query a lot more specific. We also pre-assign the variables n and m and give them labels to make the query easier to read. In this particular case, we’re asking BloodHound to find nodes with the labels User and Group, and then match those nodes using the MemberOf relationship. We added a length modifier as well to the relationship. Adding *1..3 limits the search to relationships that are between one and three links. In simple terms, give me any users that are a member of a group up to three links away. Additionally, we’re assigning the result of the pattern to the variable p and returning that variable. When we get p back, it will contain the result of each path it can find that matches our pattern we asked for.

Now that we’ve looked at the basic building blocks of queries, let’s look at a more complicated one. As an example, here’s the query we use to calculate shortest paths to Domain Admins, one of the most important queries in the BloodHound interface:

MATCH p=shortestPath((n:User)-[*1..]->(m:Group))
WHERE m.name = "DOMAIN [e-mail]"
RETURN p

Cypher is case-sensitive, and the node property “name” is always all uppercase and postfixed with the directory’s domain. In the code above, “Domain Admins” in the domain “internal.local” has become “DOMAIN [e-mail]”.

In this query, we add a few more elements to our previous ones. We still use labels to specify our nodes, but we also add another degree of specificity to our group node by restricting the group nodes that can be returned to only the DOMAIN [e-mail] by specifying the name parameter. We also use the shortestPath function. Using this function, we ask the graph to give us the shortest path it can find between each node n and the Domain Admins group. Because we didn’t specify any relationship labels, the query will use any possible relationship it can find. We also removed the limit on how many hops the database can search. By not specifying an upper limit, the database will go as many hops as possible to find a path.

There is also an allShortestPaths function available, which, as the name implies, will find every shortest path from each node to your target. Note that this results in more data analysis to perform the query and could result in higher resource consumption.

Another important part of Cypher to note is that wildcard matches are possible using regex, although the syntax for the query changes slightly. As an example, here’s the query that’s run each time you type a letter in the search bar:

MATCH (n)
WHERE n.name =~ "(?i).*searchterm.*"
RETURN n
LIMIT 10

In this query, we ask the graph to return any nodes of any type that match the search term given. The (?i) tells the graph this is a case-insensitive regex, with the .* on each side indicating that we want to match anything on either side. We limit the number of items returned to the first ten using the LIMIT keyword.

Advanced Concepts

As you build into more complicated queries, the WITH keyword will become important. The WITH keyword allows you to use multiple queries and pass the results of each query to the next step. An example of this is in the BloodHound interface whenever you click on a group node. The “Session” section displays the number of places where users in this group (including its subgroups) currently have sessions.

The UI calculates the number of sessions for the group using two separate queries put together:

MATCH p=shortestPath((m:User)-[r:MemberOf*1..]->(n:Group))
WHERE n.name = "$name_of_group"
WITH m
MATCH q=((m)<-[:HasSession]-(o:Computer))
RETURN count(o)

This query looks more complicated than we had before, so let’s break it down into two components.

MATCH p=shortestPath((m:User)-[r:MemberOf*1..]->(n:Group))
WHERE n.name = "$name_of_group"

This is the first query we run. We ask BloodHound to find the shortestPath possible from any user node to the group we specify. Note that we allow the MemberOf relationship to span any number of hops, allowing us to include users inside nested groups. This first query gives us all the effective members of the group we ask for.

MATCH q=((m)<-[:HasSession]-(o:Computer))
RETURN count(o)

This is the second query that actually gives us the session data. The variable m is carried over from the previous query and contains all the users relevant to the group we’re attempting to find sessions for. We ask BloodHound to find any computer where any of the users we found in the first step has a session using the HasSession relationship. We’re not interested in returning the relationships in this particular case, so we don’t assign a variable. Finally, we return the count of the number of computers we have sessions on. The two queries we execute are joined together using the WITH keyword. When using the keyword, you specify any variables you want to carry over from the previous part of the query. These variables will be available with the data for the next query in your chain.

Outcome

Now that we’ve explained Cypher and the syntax and all the cool ways you can narrow down search results, the next step is for you to build some new and interesting queries and start examining how you can view relationships.