How to create a parser guide (#168)

cisagov · Aug 3, 2023 · 2254367 · 2254367
1 parent 9f9475c
commit 2254367
Show file tree

Hide file tree

Showing 32 changed files with 2,461 additions and 51 deletions.
diff --git a/docs/parser-guide/Create Parser Guide.md b/docs/parser-guide/Create Parser Guide.md
diff --git a/...s/parser-core/schemas/logging.schema.json → ...guide/command-schemas/logging.schema.json b/...s/parser-core/schemas/logging.schema.json → ...guide/command-schemas/logging.schema.json
diff --git a/...rser-core/schemas/parser-info.schema.json → ...e/command-schemas/parser-info.schema.json b/...rser-core/schemas/parser-info.schema.json → ...e/command-schemas/parser-info.schema.json
diff --git a/...er-core/schemas/parser-output.schema.json → ...command-schemas/parser-output.schema.json b/...er-core/schemas/parser-output.schema.json → ...command-schemas/parser-output.schema.json
@@ -10,27 +10,24 @@
 				},
 				"filepath": {
 					"description": "Local path to the file that the log entry was found in",
-					"default": "undefined",
 					"type": "string"
 				},
 				"lineNumber": {
 					"description": "The starting line number of the log entry in the file",
-					"default": "undefined",
 					"type": "number"
 				},
 				"lineType": {
 					"description": "The type of log line if the logType is 'BEACON'",
 					"enum": ["CHECKIN", "ERROR", "INDICATOR", "INPUT", "METADATA", "MODE", "OUTPUT", "TASK"],
-					"default": "undefined",
 					"type": "string"
 				},
 				"logType": {
-					"$ref": "#/definitions/LogType",
-					"description": "The type of log entry"
+					"description": "The type of log entry",
+					"enum": ["BEACON", "DOWNLOAD", "EVENT", "KEYSTROKES", "UNKNOWN", "WEBLOG"],
+					"type": "string"
 				},
 				"dateTime": {
 					"description": "The date and time the log entry was created",
-					"default": "undefined",
 					"type": "string",
 					"format": "date-time"
 				}
@@ -59,7 +56,6 @@
 				},
 				"output": {
 					"description": "The output of the command",
-					"default": "undefined",
 					"$ref": "#/definitions/ParserLogEntry"
 				},
 				"attackIds": {
@@ -96,13 +92,11 @@
 				},
 				"startTime": {
 					"description": "The date and time the operator first sent a command",
-					"default": "undefined",
 					"type": "string",
 					"format": "date-time"
 				},
 				"endTime": {
 					"description": "The date and time the operator last sent a command",
-					"default": "undefined",
 					"type": "string",
 					"format": "date-time"
 				}
@@ -138,22 +132,18 @@
 				},
 				"os": {
 					"description": "The operating system of the host",
-					"default": "undefined",
 					"type": "string"
 				},
 				"osVersion": {
 					"description": "The version of the operating system of the host",
-					"default": "undefined",
 					"type": "string"
 				},
 				"ip": {
 					"description": "The IP address of the host",
-					"default": "undefined",
 					"type": "string"
 				},
 				"type": {
 					"description": "The type of host",
-					"default": "undefined",
 					"type": "string"
 				}
 			},
@@ -176,53 +166,44 @@
 				},
 				"ip": {
 					"description": "The IP address of the host as reported by the beacon",
-					"default": "undefined",
 					"type": "string"
 				},
 				"type": {
 					"description": "The type of beacon",
 					"enum": ["dns", "http", "https", "smb"],
-					"default": "undefined",
 					"type": "string"
 				},
 				"port": {
 					"description": "The port that the beacon is communicating over",
-					"default": "undefined",
 					"type": "number"
 				},
 				"process": {
 					"description": "The process name of the beacon",
-					"default": "undefined",
 					"type": "string"
 				},
 				"processId": {
 					"description": "The process identifier of the beacon",
-					"default": "undefined",
 					"type": "number"
 				},
 				"startTime": {
 					"description": "The date time the beacon was initialized or ran it's first command",
-					"default": "undefined",
 					"type": "string",
 					"format": "date-time"
 				},
 				"endTime": {
 					"description": "The date time the beacon ran it's last command or was terminated",
-					"default": "undefined",
 					"type": "string",
 					"format": "date-time"
 				},
 				"images": {
 					"description": "A list of images that the beacon has downloaded",
-					"default": "undefined",
 					"type": "array",
 					"items": {
 						"$ref": "#/definitions/ParserImage"
 					}
 				},
 				"files": {
 					"description": "A list of files that the beacon has uploaded or downloaded",
-					"default": "undefined",
 					"type": "array",
 					"items": {
 						"$ref": "#/definitions/ParserFile"
@@ -245,7 +226,6 @@
 				},
 				"fileName": {
 					"description": "The name of the image if the local file name is different from the name of the image",
-					"default": "undefined",
 					"type": "string"
 				}
 			},
@@ -256,7 +236,6 @@
 			"properties": {
 				"fileName": {
 					"description": "The name of the file if the local file name is different from the name of the file",
-					"default": "undefined",
 					"type": "string"
 				},
 				"filePath": {
@@ -273,8 +252,9 @@
 					"type": "string"
 				},
 				"fileFlag": {
-					"$ref": "#/definitions/FileFlag",
-					"description": "Was this file uploaded to the host or downloaded from the host"
+					"description": "Was this file uploaded to the host or downloaded from the host",
+					"enum": ["DOWNLOAD", "UPLOAD"],
+					"type": "string"
 				}
 			},
 			"required": ["dateTime", "fileFlag", "filePath"]
@@ -311,14 +291,6 @@
 				}
 			},
 			"required": ["beacons", "commands", "hosts", "links", "operators", "servers"]
-		},
-		"LogType": {
-			"enum": ["BEACON", "DOWNLOAD", "EVENT", "KEYSTROKES", "UNKNOWN", "WEBLOG"],
-			"type": "string"
-		},
-		"FileFlag": {
-			"enum": ["DOWNLOAD", "UPLOAD"],
-			"type": "string"
 		}
 	}
 }
diff --git a/...-core/schemas/parser-progress.schema.json → ...mmand-schemas/parser-progress.schema.json b/...-core/schemas/parser-progress.schema.json → ...mmand-schemas/parser-progress.schema.json
diff --git a/...schemas/parser-validate-files.schema.json → ...schemas/parser-validate-files.schema.json b/...schemas/parser-validate-files.schema.json → ...schemas/parser-validate-files.schema.json
diff --git a/docs/parser-guide/commands-api/info/enums/ServerDelineationTypes.md b/docs/parser-guide/commands-api/info/enums/ServerDelineationTypes.md
@@ -0,0 +1,34 @@
+[@redeye/parser-core](../index.md) / ServerDelineationTypes
+
+# Enumeration: ServerDelineationTypes
+
+## Table of contents
+
+### Enumeration Members
+
+- [Database](ServerDelineationTypes.md#database)
+- [Folder](ServerDelineationTypes.md#folder)
+
+## Enumeration Members
+
+### Database
+
+• **Database** = ``"Database"``
+
+server data not in any particular file/folder structure
+
+#### Defined in
+
+[upload-form.ts:54](https://github.com/cisagov/RedEye/blob/9f9475cf/parsers/parser-core/src/parser-info/upload-form.ts#L54)
+
+___
+
+### Folder
+
+• **Folder** = ``"Folder"``
+
+server data seperated into distinct folders
+
+#### Defined in
+
+[upload-form.ts:52](https://github.com/cisagov/RedEye/blob/9f9475cf/parsers/parser-core/src/parser-info/upload-form.ts#L52)
diff --git a/docs/parser-guide/commands-api/info/enums/UploadType.md b/docs/parser-guide/commands-api/info/enums/UploadType.md
@@ -0,0 +1,35 @@
+[@redeye/parser-core](../index.md) / UploadType
+
+# Enumeration: UploadType
+
+## Table of contents
+
+### Enumeration Members
+
+- [Directory](UploadType.md#directory)
+- [File](UploadType.md#file)
+
+## Enumeration Members
+
+### Directory
+
+• **Directory** = ``"Directory"``
+
+upload a directory
+
+#### Defined in
+
+[file-upload.ts:30](https://github.com/cisagov/RedEye/blob/9f9475cf/parsers/parser-core/src/parser-info/file-upload.ts#L30)
+
+___
+
+### File
+
+• **File** = ``"File"``
+
+upload a single file or a selection of multiple files
+Use this if data is in a single file like a json or csv or a selection of files like .pcap files
+
+#### Defined in
+
+[file-upload.ts:28](https://github.com/cisagov/RedEye/blob/9f9475cf/parsers/parser-core/src/parser-info/file-upload.ts#L28)
diff --git a/docs/parser-guide/commands-api/info/enums/ValidationMode.md b/docs/parser-guide/commands-api/info/enums/ValidationMode.md
@@ -0,0 +1,47 @@
+[@redeye/parser-core](../index.md) / ValidationMode
+
+# Enumeration: ValidationMode
+
+## Table of contents
+
+### Enumeration Members
+
+- [FileExtensions](ValidationMode.md#fileextensions)
+- [None](ValidationMode.md#none)
+- [Parser](ValidationMode.md#parser)
+
+## Enumeration Members
+
+### FileExtensions
+
+• **FileExtensions** = ``"FileExtensions"``
+
+validate uploaded files in client by file extensions
+
+#### Defined in
+
+[upload-form.ts:61](https://github.com/cisagov/RedEye/blob/9f9475cf/parsers/parser-core/src/parser-info/upload-form.ts#L61)
+
+___
+
+### None
+
+• **None** = ``"None"``
+
+no validation
+
+#### Defined in
+
+[upload-form.ts:59](https://github.com/cisagov/RedEye/blob/9f9475cf/parsers/parser-core/src/parser-info/upload-form.ts#L59)
+
+___
+
+### Parser
+
+• **Parser** = ``"Parser"``
+
+validate uploaded files in server with parser, parser must implement "validate-files" command
+
+#### Defined in
+
+[upload-form.ts:63](https://github.com/cisagov/RedEye/blob/9f9475cf/parsers/parser-core/src/parser-info/upload-form.ts#L63)
diff --git a/docs/parser-guide/commands-api/info/index.md b/docs/parser-guide/commands-api/info/index.md
@@ -0,0 +1,45 @@
+@redeye/parser-core
+
+# @redeye/parser-core
+
+## Table of contents
+
+### Enumerations
+
+- [ServerDelineationTypes](enums/ServerDelineationTypes.md)
+- [UploadType](enums/UploadType.md)
+- [ValidationMode](enums/ValidationMode.md)
+
+### Interfaces
+
+- [FileDisplay](interfaces/FileDisplay.md)
+- [FileUpload](interfaces/FileUpload.md)
+- [ParserInfo](interfaces/ParserInfo.md)
+- [UploadForm](interfaces/UploadForm.md)
+
+### Type Aliases
+
+- [UploadValidation](index.md#uploadvalidation)
+
+## Type Aliases
+
+### UploadValidation
+
+Ƭ **UploadValidation**: { `validate`: [`None`](enums/ValidationMode.md#none) \| [`Parser`](enums/ValidationMode.md#parser)  } \| { `acceptedExtensions`: `string`[] ; `validate`: [`FileExtensions`](enums/ValidationMode.md#fileextensions)  }
+
+The validation mode for the upload form
+
+**`Example`**
+
+```ts
+// No validation, allow uploading any folder or files
+validate = { validate: ValidationMode.None }
+// Only allow files with specific file extensions
+validate = { validate: ValidationMode.FileExtensions, acceptedExtensions: ['txt', 'png', 'jpg'] }
+// The parser has implemented the 'validate-files' command and will validate the folder of files
+validate = { validate: ValidationMode.Parser }
+```
+
+#### Defined in
+
+[upload-form.ts:76](https://github.com/cisagov/RedEye/blob/9f9475cf/parsers/parser-core/src/parser-info/upload-form.ts#L76)
diff --git a/docs/parser-guide/commands-api/info/interfaces/FileDisplay.md b/docs/parser-guide/commands-api/info/interfaces/FileDisplay.md
@@ -0,0 +1,22 @@
+[@redeye/parser-core](../index.md) / FileDisplay
+
+# Interface: FileDisplay
+
+## Table of contents
+
+### Properties
+
+- [editable](FileDisplay.md#editable)
+
+## Properties
+
+### editable
+
+• **editable**: `boolean`
+
+Whether the names of the servers inferred from the uploaded files are editable
+A user may want to change the name of a server to something more descriptive
+
+#### Defined in
+
+[upload-form.ts:85](https://github.com/cisagov/RedEye/blob/9f9475cf/parsers/parser-core/src/parser-info/upload-form.ts#L85)