Mirror of https://github.com/roostorg/osprey
github.com/roostorg/osprey
manually added images
+59
-46
+59
-46
docs/UI.md
+59
-46
docs/UI.md
···
1
1
# **Osprey User Interface Guide**
2
2
3
3
4
-
[Left Column: Query](#left-column:-query)
5
4
6
-
- [Query Box](#query-box)
5
+
The Osprey UI has several pages accessible by a left-hand menu:
7
6
8
-
- [History](#history)
7
+
9
8
10
-
- [Saved Queries](#saved-queries)
11
9
12
-
[Middle Column: Charts](#middle-column:-charts)
10
+
Home will bring you to the default page of Osprey, with three main columns.
13
11
14
-
- [Time Series Chart](#time-series-chart)
12
+
**NOTE: The Event Stream in the right column is not yet in v0, and will be available before or in v1.**
15
13
16
-
- [Top N Results](#top-n-results)
14
+
17
15
18
-
[Right Column: Event Stream](#right-column:-event-stream)
16
+
### Left Column: Query
19
17
20
-
[Query Syntax](?tab=t.h06jr5e5c3ep#heading=h.9h8pnmwkkyrc)
18
+
#### **Query Box**
21
19
22
-
- [Basic Query Structure](#actions)
20
+
The Osprey Query UI uses the same SML syntax as rules, but for searching and filtering near-real-time and historical data rather than creating new rules. Using the test data generator, you can try writing a query to look for an action called “create\_post” specifically from a given User ID.
21
+
23
22
24
-
- [Combining Conditions](#combining-conditions)
25
-
26
-
- [Using UDFs in Queries](#using-udfs-in-queries)
27
-
28
-
- [Label Queries](#label-queries)
29
-
30
-
[Example Queries](#example-queries)
31
-
32
-
The Osprey UI has several pages accessible by a left-hand menu:
33
-
34
-
35
-
Home will bring you to the default page of Osprey, with three main columns. **NOTE: The Event Stream in the right column is not yet in v0, and will be available before or in v1.**
36
-
37
-
38
-
### Left Column: Query {#left-column:-query}
39
-
40
-
#### **Query Box** {#query-box}
41
-
42
-
The Osprey Query UI uses the same SML syntax as rules, but for searching and filtering near-real-time and historical data rather than creating new rules. Using the test data generator, you can try writing a query to look for an action called “create\_post” specifically from a given User ID.
43
23
44
24
You can also use a UDF in your query. If you ever forget what a UDF does, you can hover on the information symbol for a tip:
25
+
45
26
46
27
A query can be run against a time window ranging from the last second to the last 3 months (and also a custom range):
28
+
47
29
48
30
49
31
The Osprey UI is designed to be dynamic and update in real-time. If any other component in the other two columns is interacted with, the query will automatically update and vice versa. The query also automatically populates the URL. This can be handy for sharing a specific query with someone on a team, but may present privacy risks.
50
32
51
-
#### **History** {#history}
33
+
34
+
35
+
#### **History**
52
36
53
37
Every query is logged in the Query History view, and there is a dropdown filter to only show queries that you have run.
54
38
55
-
56
39
When you hover over the query, it will also show the Top N Charts used during the query session (more on that below).
57
40
41
+
58
42
59
-
The Query History can also be accessed and seen in a different format via the left-side menu.
43
+
The Query History can also be accessed and seen in a different format via the left-side menu. From here you can filter by the user who ran the query, view the original query, and run it using the same time range the original query used.
60
44
61
-
#### **Saved Queries** {#saved-queries}
45
+
46
+
47
+
#### **Saved Queries**
62
48
63
49
If there are specific queries that are used often, Osprey provides the ability to save a query:
64
50
51
+
52
+
65
53
The user who initiated the query and when the query was first run is logged as part of the Saved Query. Saved Queries can also be accessed via the left-side menu. The user who saved the query and what time it was saved is logged and visible. There is a drop-down menu at the top to filter saved queries by users.
66
54
55
+
67
56
68
-
### Middle Column: Charts {#middle-column:-charts}
57
+
### Middle Column: Charts
69
58
70
59
The middle column in Osprey shows two types of charts: **Time Series** and **Top N Results**. Both sections provide the ability to add extra charts to see different slices of time or types of top results.
71
60
61
+
72
62
73
-
#### **Time Series Chart** {#time-series-chart}
63
+
#### **Time Series Chart**
74
64
75
65
The Time Series chart shows a visualization of the results in the query over a period of time. The time ranges include:
76
66
···
83
73
* Month
84
74
85
75
Hovering over a bar in the time series chart shows how many events took place during that time.
76
+
77
+
86
78
87
79
There is also a time and date picker above the time series chart where you can set a custom range:
80
+
88
81
89
82
An extra table can be added for another view of a different unit of time. To get rid of the table, you can “[yeet](https://www.urbandictionary.com/define.php?term=Yeet) it”.
83
+
90
84
91
85
92
-
#### **Top N Results** {#top-n-results}
86
+
#### **Top N Results**
93
87
94
88
Adding a Top N Results table populates a table with the top results for the results of the query. You can view and assign labels to a specific entity by hovering over it and clicking “Edit Labels”
89
+
95
90
91
+
**NOTE: Labels are not yet in v0**
92
+
93
+
96
94
97
-
### Right Column: Event Stream {#right-column:-event-stream}
95
+
You can also select PoP (Period over Period) to compare the query results with results from a window of time in the past to see the delta.
96
+
97
+
98
+
99
+
### Right Column: Event Stream
98
100
99
101
**The Event Stream is not yet in v0, and will be available before or in v1.**
102
+
100
103
The Event Stream is essentially Osprey's "live feed" and investigation dashboard where security teams can:
101
104
102
105
* Monitor real-time activity
···
106
109
* Drill down into specific users/entities
107
110
108
111
It provides a more detailed view of each event that matches the query. The Event Stream can show metadata related to accounts that can link to other internal tools that provide detailed information about an account and/or further enforcement actions.
112
+
113
+
109
114
110
115
The event stream is also viewable in a card format vs a list format (list format shown in the screenshot).
111
116
112
117
Osprey users may have personal preferences on how to do investigations and what information is most helpful for them. Osprey makes it easy to customize the types of information shown in the Event Stream by clicking “Summary Features”
118
+
113
119
114
120
115
121
### Labeling
116
122
117
123
**Note: Labels are not yet in v0, but will come in v1**
118
124
Any unique entity can be labeled in the Osprey UI. This manual labeling tool is used by Safety teams to tag individual entities (users, IPs, emails, etc.) with labels. Labels are essentially the manual annotation tool that feeds into Osprey's automated rule system, allowing human judgment to enhance machine detection. Labels can be positive, negative, or neutral. Examples:
119
-
**Negative Labels: Harmful/problematic behavior**
120
125
126
+
**Negative Labels: Harmful/problematic behavior**
121
127
* Examples: "spammer", "bot", "banned", "suspicious"
122
128
123
129
**Positive Labels: Good/trusted behavior**
124
-
125
130
* Examples: "verified", "trusted", "premium\_user"
126
131
127
132
**Neutral Labels: Informational tags**
128
-
129
133
* Examples: "new\_user", "from\_mobile", "beta\_tester"
130
134
131
135
132
136
Below are examples of a new label interface from v0, and an example from Discord’s usage of labels (coming in v1).
137
+
138
+
133
139
134
140
135
141
### UDF Documentation
136
142
137
143
The UDF Documentation page can be accessed via the left-side menu. It dynamically updates based on the code, so any new UDFs added will show up on this page. This page essentially serves as the "API reference" for the SML language, making it easy for users to discover and properly use all available functions when writing rules and queries.
144
+
138
145
139
146
This page can be used as a manual for writing SML rules or queries, guide for understanding parameter types and requirements, and act as a plugin discovery portal to explore what custom UDFs are loaded.
140
147
···
143
150
**Note: Since Bulk Labeling relies on Labels, it does not yet work in v0.**
144
151
145
152
There are two ways to bulk label items in Osprey: the left-side menu and via the chart column. In this example, you can bulk label all the users that have posted a message that is not empty:
153
+
146
154
147
-
Bulk labels can be dangerous if there’s a false positive\! Osprey provides a counter of how many unique entities are about to be bulk labeled at the top. Labels can be positive, negative, or neutral. A reason must be provided when labeling anything. Each bulk job will create a unique task ID and log the user who initiated the bulk job, the status of the bulk labeling, and a link to the query that the bulk job originated from.
155
+
156
+
**Bulk labels can be dangerous if there’s a false positive\!** Osprey provides a counter of how many unique entities are about to be bulk labeled at the top. Labels can be positive, negative, or neutral. A reason must be provided when labeling anything. Each bulk job will create a unique task ID and log the user who initiated the bulk job, the status of the bulk labeling, and a link to the query that the bulk job originated from.
148
157
149
158
To view all bulk labeling jobs that have been done, click into “Bulk Job History” from the left-side menu. You’ll need the unique task ID to look up a bulk job.
159
+
150
160
151
161
152
162
### Rule Visualizer
···
159
169
* **Blue square:** rule
160
170
* **Green circle:** label downstream of a rule
161
171
172
+
173
+
174
+
162
175
### Query Syntax
163
176
164
-
#### **Actions** {#actions}
177
+
#### **Actions**
165
178
166
179
Actions are events that are sent to Osprey. An event is simply something that happens. When a user does something like create a post, send a message, change their username, etc an event happens to represent that. There are probably a lot of events emitted in your org, and Osprey doesn’t need to consume all of them.
167
180
···
207
220
MessageText != Null
208
221
```
209
222
210
-
#### **Combining Conditions** {#combining-conditions}
223
+
#### **Combining Conditions**
211
224
212
225
Let’s say you’re looking for any matches where a user tried to login more than 3 times. You can create a query to check for two types of data fields: “EventType” and “LoginAttempts”.
213
226
···
222
235
(UserId == 123) or (UserId == 456)
223
236
```
224
237
225
-
#### **Using UDFs in Queries** {#using-udfs-in-queries}
238
+
#### **Using UDFs in Queries**
226
239
227
240
UDFs (read more [here](https://github.com/roostorg/osprey/blob/f16da6e5c32ae124c3cc6e2d7efded7cea1ac726/docs/rules.md#user-defined-functions-udfs)) are a powerful part of queries. Once you define a UDF with the specific desired logic, you can reference it in a query.
228
241
···
237
250
ListLength(list=UserConnections) > 10
238
251
```
239
252
240
-
#### **Label Queries** {#label-queries}
253
+
#### **Label Queries**
241
254
242
255
**Important Note: Labels are not yet in v0, so these will not work in the UI.**
243
256
···
254
267
255
268
###
256
269
257
-
### Example Queries {#example-queries}
270
+
### Example Queries
258
271
259
272
```py
260
273
# Find suspicious login attempts: