add atom-tools to documentation

Signed-off-by: Aryan Rajoria <aryanrajoria1003@gmail.com>

docs/docs/Features/check.md

@@ -0,0 +1,35 @@
+---
+title: Check Reachables
+---
+
+## Check Reachables
+
+The check-reachable command takes either a package:version or filename:line_number/line_number_range
+
+`check-reachable -i reachable_slice.json -p colors:1.0.0`
+`check-reachable -i reachable_slice.json -p @colors/colors:1.0.0`
+`check-reachable -i reachable_slice.json -l file:20`
+`check-reachable -i reachable_slice.json -l file:20-40`
+
+```
+Description:
+  Find out if there are hits for a given package:version or file:linenumber in an atom slice.
+
+Usage:
+  check-reachable [options]
+
+Options:
+  -i, --input-slice=INPUT-SLICE  Slice file
+  -p, --pkg=PKG                  Package to search for in the format of <package_name>:<version>
+  -l, --location=LOCATION        Filename with line number to search for in the format of <filename>:<linenumber>
+  -h, --help                     Display help for the given command. When no command is given display help for the list command.
+  -q, --quiet                    Do not output any message.
+  -V, --version                  Display this application version.
+      --ansi                     Force ANSI output.
+      --no-ansi                  Disable ANSI output.
+  -n, --no-interaction           Do not ask any interactive question.
+  -v|vv|vvv, --verbose           Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug.
+
+Help:
+  The check-reachables command checks for reachable flows for a package:version or file:linenumber in an atom slice.
+```

docs/docs/Features/convert.md

@@ -0,0 +1,42 @@
+---
+title: Convert
+---
+
+## Convert
+
+The convert command can be used to output an atom slice in a different format. The current
+capabilities are limited to processing usages in order to generate endpoints for an openapi 3.x
+paths object. Future iterations will populate the path item objects with more details based on
+atom slices.
+
+```
+Description:
+  Convert an atom slice to a different format
+
+Usage:
+  convert [options]
+
+Options:
+  -f, --format=FORMAT              Destination format [default: "openapi3.0.1"]
+  -i, --input-slice=INPUT-SLICE  Usages slice file
+  -t, --type=TYPE                  Origin type of source on which the atom slice was generated. [default: "java"]
+  -o, --output-file=OUTPUT-FILE    Output file [default: "openapi_from_slice.json"]
+  -s, --server=SERVER              The server url to be included in the server object.
+  -h, --help                       Display help for the given command. When no command is given display help for the list command.
+  -q, --quiet                      Do not output any message.
+  -V, --version                    Display this application version.
+      --ansi                       Force ANSI output.
+      --no-ansi                    Disable ANSI output.
+  -n, --no-interaction             Do not ask any interactive question.
+  -v|vv|vvv, --verbose             Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug.
+
+Help:
+  The convert command converts an atom slice to a different format.
+      Currently supports outputting an OpenAPI 3.x document based on a usages
+      slice.
+```
+
+**Example**
+
+> `atom-tools convert -i usages.slices.json -f openapi3.0.1 -o openapi_usages.json -t java -s https://myserver.com`
+

docs/docs/Features/filter.md

@@ -0,0 +1,132 @@
+---
+title: Filter
+---
+
+## Filter
+
+The filter command can be run on its own to produce a filtered slice or used before another command
+to filter a slice before executing another command against the results.
+
+>**Filters operate on an inclusive-or basis. If you want to operate on an 'and' basis, 
+> [chain](#chaining-filter-commands) the filter commands.**
+
+**Mode**
+
+The default mode creates a regular expression from the value given. Fuzzy mode is specified using
+the -f option and a number between 0-100 indicating how close the result must be to be a match. 
+Note that to exactly match the specified input, you need to either include regex anchors at the 
+beginning and end or use -f 100 (to specify a 100% match).
+
+`filter -f 100 --criteria filename=path/to/file/server.ts -i usages.json`
+
+`filter --criteria filename=^path/to/file/server.ts$ -i usages.json`
+
+Regex word boundaries can be used if you only want to be exact about the filename.
+
+`filter --criteria filename=\bserver.ts$ -i usages.json`
+
+This will filter files named server.ts - without the \b, files like ftpserver.ts would also be matched.
+
+>Note: You can search for a file name without including the path if needed and fuzzing ratios will be computed based 
+> only on the file name.
+
+##### Chaining filter commands
+
+The filter command can act on itself by specifying an additional filter command as an argument.
+This may desirable for certain use cases where one wishes some criteria to be required.
+
+**Example**
+
+`atom-tools filter -i slices.json --criteria filename=myfile -e "filter --criteria resolvedMethod=mymethod,resolvedMethod=mymethod2 convert"`
+
+This would be equivalent to
+
+`if fileName.contains('myfile') and (resolvedMethod.contains('mymethod') or resolvedMethod.contains('mymethod2')):`
+
+##### Available attributes (not case-sensitive):
+
+*For usages slices*
+- callName
+- fileName
+- fullName
+- name
+- resolvedMethod
+- signature
+
+| attribute      | locations searched                                                                                                                                                      | reachables locations                       |
+|----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------------------------------------------|
+| callName       | objectSlices.usages.argToCalls<br/>objectSlices.usages.invokedCalls<br/>userDefinedTypes.procedures,                                                                    |                                            |
+| fileName       | objectSlices<br/>userDefinedTypes                                                                                                               |                                            |                                                                                                                          |
+| fullName       | objectSlices                                                                                                                                                            |                                            |
+| name           | objectSlices.usages.targetObj<br/>objectSlices.usages.definedBy<br/>userDefinedTypes.fields                                                                             |                                            |
+| purl           |                                                                                                                                                                         | reachables.purls<br/>reachables.flows.tags |
+| resolvedMethod | objectSlices.usages.targetObj<br/>objectSlices.usages.definedBy<br/>objectSlices.usages.argToCalls<br/>objectSlices.usages.invokedCalls<br/>userDefinedTypes.procedures |                                            |
+| signature      | objectSlices                                                                                                                                                            |                                            |                                                                                                                                                         |                      |
+
+#### Searching reachables for package name/version
+
+This option filters reachables to the given package name and version in the format of name:version
+
+`--package mypackage:1.0.0`
+
+#### Criteria syntax
+
+Multiple criteria can be given by using a comma as a separator (no space)
+
+`--criteria [attribute]=[value],[attribute2]=[value],...`
+
+#### Usage
+
+```
+Description:
+  Filter an atom slice based on specified criteria.
+
+Usage:
+  filter [options]
+
+Options:
+  -i, --input-slice=INPUT-SLICE  Slice file to filter.
+  -c, --criteria=CRITERIA        Filter based on an attribute of the slice. May be a Python regular expression. Please see documentation for syntax.
+  -o, --outfile=OUTFILE          File to re-export filtered slice to.
+  -f, --fuzz=FUZZ                Minimum percentage to match with the given criteria INSTEAD of using a regex. Must be a number between 0 and 100.
+  -e, --execute=EXECUTE          Command to execute after filtering. [default: "export"]
+  -h, --help                     Display help for the given command. When no command is given display help for the list command.
+  -q, --quiet                    Do not output any message.
+  -V, --version                  Display this application version.
+      --ansi                     Force ANSI output.
+      --no-ansi                  Disable ANSI output.
+  -n, --no-interaction           Do not ask any interactive question.
+  -v|vv|vvv, --verbose           Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug.
+
+```
+
+#### Examples
+
+_**Filter a query**_
+
+The below will produce endpoints from the server.ts file located within the line number range of
+50-70.
+
+`atom-tools filter -i usages.slices.json --criteria fileName=server.ts -e "query-endpoints -l 50-70"`
+
+_**Filter with the convert command.**_
+
+`atom-tools filter -i usages.slices.json --criteria fileName=server.ts -e "convert -f openapi3.0.1 -o openapi_usages.json -t java"`
+
+The above will produce an OpenAPI document based only on slices generated from server.ts.
+
+_**Filter based on another attribute**_
+Create a filtered json that only includes slices where the resolved method equals "validateSignup".
+Since no command is specified, the filtered slice will only be written to file.
+
+`atom-tools -i usages.slices.json filter --criteria resolvedMethod=validateSignup`
+
+_**Filtering can also be used to exclude. The first example could be changed to exclude server.ts with
+the following:**_
+
+`atom-tools filter --criteria fileName!=server.ts usages.slices.json convert -f openapi3.0.1 -o openapi_usages.json -t java `
+
+****_Multiple filter criteria may be included. The following example will produce a filtered slice based
+only on server.ts and router.ts slices._****
+
+`atom-tools filter --criteria fileName=server.ts,callName=router.ts usages.slices.json`

docs/docs/Features/query.md

@@ -0,0 +1,28 @@
+---
+title: Query Endpoints
+---
+
+## Query Endpoints
+Query endpoints generates a list of endpoints and returns the output directly to the console.
+
+>Note: To suppress logging messages and ONLY output the results, use --quiet/-q
+
+**_Examples_**
+
+Query returning all endpoints, including filenames and line numbers
+
+`query-endpoints -i usages.slices -t js`
+
+Query returning all endpoints without filenames and line numbers
+
+`query-endpoints --sparse -i usages.slices -t js`
+
+Query filtering by line number or line number range
+
+`query-endpoints -i usages.slices -t js -f 50`
+
+`query-endpoints -i usages.slices -t js -f 50-70`
+
+Query using filter command to target by both filename and line number range
+
+`filter -i usages.slices -t js -c filename=server.ts -e "query-endpoints -f 50-70"`

docs/docs/Features/validate.md

@@ -0,0 +1,37 @@
+---
+title: Validate Lines
+---
+
+## Validate Lines
+
+The validate-lines command checks the accuracy of the line numbers reported by
+atom against your source files.
+
+```
+Description:
+  Check the accuracy of the line numbers in an atom slice.
+
+Usage:
+  validate-lines [options]
+
+Options:
+  -i, --input-slice=INPUT-SLICE  Slice file to validate. [default: "slices.json"]
+  -t, --type=TYPE                Origin type of source on which the atom slice was generated. [default: "java"]
+  -d, --base-path=BASE-PATH      This should be the same path that was used by atom when the slice was generated.
+  -l, --interval=INTERVAL        Try matching within a range. Ex. slice has line number 567, with interval of 5, we check lines 562-572. Use 0 for exact matching. [default: 5]
+  -r, --report=REPORT            Output summary to file.  [default: "output.txt"]
+  -j, --export-json=EXPORT-JSON  JSON report file to store invalid lines. Include valid lines as well using -v flag.
+  -h, --help                     Display help for the given command. When no command is given display help for the list command.
+  -q, --quiet                    Do not output any message.
+  -V, --version                  Display this application version.
+      --ansi                     Force ANSI output.
+      --no-ansi                  Disable ANSI output.
+  -n, --no-interaction           Do not ask any interactive question.
+  -v|vv|vvv, --verbose           Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug.
+  
+Help:
+  Validate source file line numbers in an atom usages or reachables slice.
+```
+
+**Example**
+> `atom-tools validate-lines -t java -j project_json_report.json -i usages.slices.json -d /home/my_project_dir`

docs/docs/cli.md

@@ -0,0 +1,40 @@
+---
+sidebar_position: 3
+title: CLI Usage
+---
+
+## CLI Usage
+
+Atom-tools uses py-poetry/cleo to construct its command-line interface and therefore uses the same
+sorts of conventions as the Python package management utility poetry.
+
+To access the commands help menu, enter `atom-tools list` for a list of available commands.
+
+Individual command options can be accessed with `atom-tools help ` and the command name (
+e.g. `atom-tools help
+convert`).
+
+```
+Atom Tools (version 0.6.0)
+
+Usage:
+  command [options] [arguments]
+
+Options:
+  -h, --help            Display help for the given command. When no command is given display help for the list command.
+  -q, --quiet           Do not output any message.
+  -V, --version         Display this application version.
+      --ansi            Force ANSI output.
+      --no-ansi         Disable ANSI output.
+  -n, --no-interaction  Do not ask any interactive question.
+  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug.
+
+Available commands:
+  check-reachable  Find out if there are hits for a given package:version or file:linenumber in an atom slice.
+  convert          Convert an atom slice to a different format.
+  filter           Filter an atom slice based on specified criteria.
+  help             Displays help for a command.
+  list             Lists commands.
+  query-endpoints  List elements to display in the console.
+  validate-lines   Check the accuracy of the line numbers in an atom slice.
+```

docs/docs/getting-started.md

@@ -0,0 +1,8 @@
+---
+sidebar_position: 1
+title: Getting Started
+slug: /
+---
+
+# Getting Started with Atom-tools
+

docs/docs/install.md

@@ -0,0 +1,23 @@
+---
+sidebar_position: 2
+title: Installation
+---
+
+# Installing Atom-tools
+
+Running atom tools requires the need of atom project.
+
+## Install atom
+
+This program does not generate slices; its purpose is to manipulate slices generated by atom. The
+current documentation for atom is housed in
+the [AppThreat/atom](https://github.com/AppThreat/atom?tab=readme-ov-file) GitHub repository.
+
+Atom can easily be installed from
+a [native image](https://github.com/AppThreat/atom#atom-native-image) or via
+npm `npm install -g @appthreat/atom`.
+
+## Atom-tools installation
+
+`pip install atom-tools`
+

docs/docusaurus.config.ts

@@ -38,6 +38,7 @@ const config: Config = {
         docs: {
           sidebarPath: './sidebars.ts',
           // Please change this to your repo.
+          routeBasePath: '/',
           // Remove this to remove the "edit this page" links.
           editUrl:
             'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',

docs/sidebars.ts

@@ -14,18 +14,22 @@ import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
  */
 const sidebars: SidebarsConfig = {
   // By default, Docusaurus generates a sidebar from the docs folder structure
-  // tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],
+  tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],
 
   // But you can create a sidebar manually
-  tutorialSidebar: [
-    'intro',
-    'hello',
-    {
-      type: 'category',
-      label: 'Tutorial',
-      items: ['tutorial-basics/create-a-document'],
-    },
-  ],
+  // tutorialSidebar: [
+  //   'intro',
+  //   'hello',
+  //   {
+  //     type: 'category',
+  //     label: 'Tutorial',
+  //     items: ['tutorial-basics/create-a-document'],
+  //   },
+  // ],
+
+  // tutorialSidebar: [
+  //   'getting-started',
+  // ],
 };
 
 export default sidebars;