Mirror of https://github.com/roostorg/osprey
github.com/roostorg/osprey
remove broken references to images in code
+13
-22
+13
-22
docs/UI.md
+13
-22
docs/UI.md
···
31
31
32
32
The Osprey UI has several pages accessible by a left-hand menu:
33
33
34
-
### ![][image1]
35
34
36
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.**
37
36
38
-
![][image2]
39
37
40
38
### Left Column: Query {#left-column:-query}
41
39
···
43
41
44
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.
45
43
46
-
![][image3]
47
44
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:
48
45
49
-
![][image4]
50
46
A query can be run against a time window ranging from the last second to the last 3 months (and also a custom range):
51
-
![][image5]![][image6]
47
+
52
48
53
49
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.
54
-
![][image7]
55
50
56
51
#### **History** {#history}
57
52
58
53
Every query is logged in the Query History view, and there is a dropdown filter to only show queries that you have run.
59
54
60
-
#### **![][image8]**
61
55
62
56
When you hover over the query, it will also show the Top N Charts used during the query session (more on that below).
63
57
64
-
#### **![][image9]**
65
58
66
59
The Query History can also be accessed and seen in a different format via the left-side menu.
67
-
![][image10]
68
60
69
61
#### **Saved Queries** {#saved-queries}
70
62
71
63
If there are specific queries that are used often, Osprey provides the ability to save a query:
72
-
![][image11]
64
+
73
65
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.
74
-
![][image12]
66
+
75
67
76
68
### Middle Column: Charts {#middle-column:-charts}
77
69
78
70
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.
79
-
![][image13]
71
+
80
72
81
73
#### **Time Series Chart** {#time-series-chart}
82
74
···
91
83
* Month
92
84
93
85
Hovering over a bar in the time series chart shows how many events took place during that time.
94
-
![][image14]
86
+
95
87
There is also a time and date picker above the time series chart where you can set a custom range:
96
-
![][image15]
88
+
97
89
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”.
98
-
![][image16]
90
+
99
91
100
92
#### **Top N Results** {#top-n-results}
101
93
102
94
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”
103
-
![][image17]
95
+
104
96
105
97
### Right Column: Event Stream {#right-column:-event-stream}
106
98
···
114
106
* Drill down into specific users/entities
115
107
116
108
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.
117
-
![][image18]
109
+
118
110
The event stream is also viewable in a card format vs a list format (list format shown in the screenshot).
119
111
120
112
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”
121
-
![][image19]
113
+
122
114
123
115
### Labeling
124
116
···
139
131
140
132
Below are examples of a new label interface from v0, and an example from Discord’s usage of labels (coming in v1).
141
133
142
-
![][image20]![][image21]
143
134
144
135
### UDF Documentation
145
136
146
137
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.
147
-
![][image22]
138
+
148
139
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.
149
140
150
141
### Bulk Labeling
···
152
143
**Note: Since Bulk Labeling relies on Labels, it does not yet work in v0.**
153
144
154
145
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:
155
-
![][image23]
146
+
156
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.
157
148
158
149
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
-
![][image24]
150
+
160
151
161
152
### Rule Visualizer
162
153