Skip to content

Commit 4fe07d4

Browse files
regulartimregulartim
committed
add docs for Cowrie Session API
1 parent b381961 commit 4fe07d4

File tree

1 file changed

+98
-15
lines changed

1 file changed

+98
-15
lines changed

‎docs/GreedyBear/Usage.md‎

Lines changed: 98 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Usage
22

3-
## Feeds
3+
## Feeds API
44

55
GreedyBear is created with the aim to collect the information from the TPOTs and generate some actionable feeds, so that they can be easily accessible and act as valuable information to prevent and detect attacks.
66

@@ -65,7 +65,7 @@ These predictions are based on historical interaction patterns and are updated o
6565

6666
Check the [API specification](https://intelowlproject.github.io/docs/GreedyBear/Api-docs/#docs.Submodules.GreedyBear.api.views.feeds.feeds_advanced) or the to get all the details about how to use the available APIs.
6767

68-
## Advanced Feeds
68+
## Advanced Feeds API
6969

7070
For authenticated users, GreedyBear offers an additional API endpoint that provides similar functionality to the Feeds API but with enhanced customization options.
7171
```
@@ -90,7 +90,7 @@ Check the [API specification](https://intelowlproject.github.io/docs/GreedyBear/
9090

9191
This "Advanced Feeds" API is protected through authentication. Please reach out [Matteo Lodi](https://twitter.com/matte_lodi) or another member of [The Honeynet Project](https://twitter.com/ProjectHoneynet) if you are interested in gain access to this API.
9292

93-
## Enrichment
93+
## Enrichment API
9494

9595
GreedyBear provides an easy-to-query API to get the information available in GB regarding the queried observable (domain or IP address).
9696

@@ -102,27 +102,110 @@ This "Enrichment" API is protected through authentication. Please reach out [Mat
102102

103103
If you would like to leverage this API without the need of writing even a line of code and together with a lot of other awesome tools, consider using [IntelOwl](https://github.com/intelowlproject/IntelOwl).
104104

105-
## Command Sequence
106105

107-
This API provides information about command sequences detected by the [Cowrie](https://github.com/cowrie/cowrie) honeypot, allowing retrieval by either IP address or command sequence hash.
106+
## Cowrie Session API
108107

108+
For authenticated users, GreedyBear offers an API to retrieve session data from the [Cowrie](https://github.com/cowrie/cowrie) honeypot including command sequences, credentials, and session details. Queries can be performed using either an IP address to find all sessions from that source, or a SHA-256 hash to find sessions containing a specific command sequence.
109+
110+
You can query this API endpoint using the following URL:
109111
```
110-
https://<greedybear_site>/api/command_sequence?query=<observable>
112+
https://<greedybear_site>/api/cowrie_session?query=<observable>
111113
```
112114

113-
The available query parameters are:
114-
115-
- query (required): either an IP address or a SHA-256 hash of a command or a sequence of commands to search for
116-
- include_similar (optional): when present, returns related command sequences from the same cluster
115+
### Authentication
116+
This API is protected through authentication. Please reach out [Matteo Lodi](https://twitter.com/matte_lodi) or another member of [The Honeynet Project](https://twitter.com/ProjectHoneynet) if you are interested in gain access to this API on the [Honeynet instance](https://greedybear.honeynet.org/) of GreedyBear.
117+
118+
### Query Parameters
119+
- *query* (required): The search term, can be either an IP address or the SHA-256 hash of a command sequence. When generating a SHA-256 hash to query a multi-line command sequence, ensure you join all command lines with a newline character (`\n`) before calculating the hash. This matches our internal hashing method which uses Python's `"\n".join(sequence)` function.
120+
- *include_similar* (optional): When `true`, the result is expanded to include all sessions that executed command sequences belonging to the same cluster(s) as command sequences found in the initial query result. Requires CLUSTER_COWRIE_COMMAND_SEQUENCES enabled iin the `env_file`.
121+
- *include_credentials* (optional): When `true`, the response includes all credentials used across matching Cowrie sessions. Credentials are delivered in the `username | password` format.
122+
- *include_session_data* (optional): When `true`, the response includes detailed information about matching Cowrie sessions.
123+
124+
### Responses
125+
- Response (200): JSON object containing:
126+
- query (str): The original query parameter
127+
- commands (list[str]): Unique command sequences (newline-delimited strings)
128+
- sources (list[str]): Unique source IP addresses
129+
- credentials (list[str], optional): Unique credentials if include_credentials=true
130+
- sessions (list[object], optional): Session details if include_session_data=true
131+
- time (datetime): Session start time
132+
- duration (float): Session duration in seconds
133+
- source (str): Source IP address
134+
- interactions (int): Number of interactions in session
135+
- credentials (list[str]): Credentials used in this session
136+
- commands (str): Command sequence executed (newline-delimited)
137+
- Response (400): Bad Request - Missing or invalid query parameter
138+
- Response (404): Not Found - No matching sessions found
139+
140+
141+
### Examples
142+
143+
#### Example 1: Query an IP Address with Credentials
144+
**Request:**
145+
```
146+
GET /api/cowrie_session?query=60.188.124.194&include_credentials=true
147+
```
117148

118-
Notes:
149+
**Response:**
150+
```json
151+
{
152+
"license": "https://github.com/honeynet/GreedyBear/blob/main/FEEDS_LICENSE.md",
153+
"query": "60.188.124.194",
154+
"commands": [
155+
"uname -a"
156+
],
157+
"sources": [
158+
"60.188.124.194"
159+
],
160+
"credentials": [
161+
"ADMIN | #K2_7f@c048Z",
162+
"albert | admin",
163+
//...
164+
"zccloud | d5EJQLN0nid8B6HXHHxP"
165+
]
166+
}
167+
```
168+
#### Example 2: Query a Command Sequence Hash:
169+
**Request:**
170+
```
171+
GET /api/cowrie_session?query=28ba533b0f3c4df63d6b4a5ead73860697bdf735bb353e4ca928474889eb8a15
172+
```
119173

120-
- When generating a SHA-256 hash to query a multi-line command sequence, ensure you join all command lines with a newline character (`\n`) before calculating the hash. This matches our internal hashing method which uses Python's `"\n".join(sequence)` function.
121-
- For the `include_similar` parameter to work, `CLUSTER_COWRIE_COMMAND_SEQUENCES` must be enabled in the `env_file`.
174+
**Response:**
175+
```json
176+
{
177+
"query": "28ba533b0f3c4df63d6b4a5ead73860697bdf735bb353e4ca928474889eb8a15",
178+
"commands": [
179+
"uname -a"
180+
],
181+
"sources": [
182+
"60.188.124.194"
183+
]
184+
}
185+
```
186+
#### Example 3: Query an IP Address with Similar Sessions:
187+
**Request:**
188+
```
189+
/api/cowrie_session?query=60.188.124.194&include_similar=true
190+
```
122191

123-
This "Command Sequence" API is protected through authentication. Please reach out [Matteo Lodi](https://twitter.com/matte_lodi) or another member of [The Honeynet Project](https://twitter.com/ProjectHoneynet) if you are interested in gain access to this API.
192+
**Response:**
193+
```json
194+
{
195+
"query": "60.188.124.194",
196+
"commands": [
197+
"uname -a",
198+
"uname -s -m"
199+
],
200+
"sources": [
201+
"60.188.124.194",
202+
"103.106.104.87",
203+
"183.204.86.10",
204+
"221.203.35.59"
205+
]
206+
}
207+
```
124208

125-
If you would like to leverage this API without the need of writing even a line of code and together with a lot of other awesome tools, consider using [IntelOwl](https://github.com/intelowlproject/IntelOwl).
126209

127210

128211
## User management

0 commit comments

Comments
 (0)