From 547c540ce3aa0ed29ec0c76dc433771bb22c204d Mon Sep 17 00:00:00 2001 From: Aryan Rajoria Date: Fri, 3 Jan 2025 00:20:07 -0500 Subject: [PATCH] add atom-tools to documentation Signed-off-by: Aryan Rajoria --- docs/docs/Features/check.md | 35 +++++ docs/docs/Features/convert.md | 42 ++++++ docs/docs/Features/filter.md | 132 ++++++++++++++++++ docs/docs/Features/query.md | 28 ++++ docs/docs/Features/validate.md | 37 +++++ docs/docs/cli.md | 40 ++++++ docs/docs/getting-started.md | 8 ++ docs/docs/install.md | 23 +++ docs/{docs => docs_old}/hello.md | 0 docs/{docs => docs_old}/intro.md | 0 .../tutorial-basics/_category_.json | 0 .../tutorial-basics/congratulations.md | 0 .../tutorial-basics/create-a-blog-post.md | 0 .../tutorial-basics/create-a-document.md | 0 .../tutorial-basics/create-a-page.md | 0 .../tutorial-basics/deploy-your-site.md | 0 .../tutorial-basics/markdown-features.mdx | 0 .../tutorial-extras/_category_.json | 0 .../img/docsVersionDropdown.png | Bin .../tutorial-extras/img/localeDropdown.png | Bin .../tutorial-extras/manage-docs-versions.md | 0 .../tutorial-extras/translate-your-site.md | 0 docs/docusaurus.config.ts | 1 + docs/sidebars.ts | 24 ++-- package-lock.json | 6 + 25 files changed, 366 insertions(+), 10 deletions(-) create mode 100644 docs/docs/Features/check.md create mode 100644 docs/docs/Features/convert.md create mode 100644 docs/docs/Features/filter.md create mode 100644 docs/docs/Features/query.md create mode 100644 docs/docs/Features/validate.md create mode 100644 docs/docs/cli.md create mode 100644 docs/docs/getting-started.md create mode 100644 docs/docs/install.md rename docs/{docs => docs_old}/hello.md (100%) rename docs/{docs => docs_old}/intro.md (100%) rename docs/{docs => docs_old}/tutorial-basics/_category_.json (100%) rename docs/{docs => docs_old}/tutorial-basics/congratulations.md (100%) rename docs/{docs => docs_old}/tutorial-basics/create-a-blog-post.md (100%) rename docs/{docs => docs_old}/tutorial-basics/create-a-document.md (100%) rename docs/{docs => docs_old}/tutorial-basics/create-a-page.md (100%) rename docs/{docs => docs_old}/tutorial-basics/deploy-your-site.md (100%) rename docs/{docs => docs_old}/tutorial-basics/markdown-features.mdx (100%) rename docs/{docs => docs_old}/tutorial-extras/_category_.json (100%) rename docs/{docs => docs_old}/tutorial-extras/img/docsVersionDropdown.png (100%) rename docs/{docs => docs_old}/tutorial-extras/img/localeDropdown.png (100%) rename docs/{docs => docs_old}/tutorial-extras/manage-docs-versions.md (100%) rename docs/{docs => docs_old}/tutorial-extras/translate-your-site.md (100%) create mode 100644 package-lock.json diff --git a/docs/docs/Features/check.md b/docs/docs/Features/check.md new file mode 100644 index 0000000..59ffff3 --- /dev/null +++ b/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 : + -l, --location=LOCATION Filename with line number to search for in the format of : + -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. +``` diff --git a/docs/docs/Features/convert.md b/docs/docs/Features/convert.md new file mode 100644 index 0000000..9c233c7 --- /dev/null +++ b/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` + diff --git a/docs/docs/Features/filter.md b/docs/docs/Features/filter.md new file mode 100644 index 0000000..6eee936 --- /dev/null +++ b/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
objectSlices.usages.invokedCalls
userDefinedTypes.procedures, | | +| fileName | objectSlices
userDefinedTypes | | | +| fullName | objectSlices | | +| name | objectSlices.usages.targetObj
objectSlices.usages.definedBy
userDefinedTypes.fields | | +| purl | | reachables.purls
reachables.flows.tags | +| resolvedMethod | objectSlices.usages.targetObj
objectSlices.usages.definedBy
objectSlices.usages.argToCalls
objectSlices.usages.invokedCalls
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` diff --git a/docs/docs/Features/query.md b/docs/docs/Features/query.md new file mode 100644 index 0000000..de9b964 --- /dev/null +++ b/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"` diff --git a/docs/docs/Features/validate.md b/docs/docs/Features/validate.md new file mode 100644 index 0000000..51c9e0b --- /dev/null +++ b/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` diff --git a/docs/docs/cli.md b/docs/docs/cli.md new file mode 100644 index 0000000..f3db403 --- /dev/null +++ b/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. +``` \ No newline at end of file diff --git a/docs/docs/getting-started.md b/docs/docs/getting-started.md new file mode 100644 index 0000000..986a2ab --- /dev/null +++ b/docs/docs/getting-started.md @@ -0,0 +1,8 @@ +--- +sidebar_position: 1 +title: Getting Started +slug: / +--- + +# Getting Started with Atom-tools + diff --git a/docs/docs/install.md b/docs/docs/install.md new file mode 100644 index 0000000..cd05140 --- /dev/null +++ b/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` + diff --git a/docs/docs/hello.md b/docs/docs_old/hello.md similarity index 100% rename from docs/docs/hello.md rename to docs/docs_old/hello.md diff --git a/docs/docs/intro.md b/docs/docs_old/intro.md similarity index 100% rename from docs/docs/intro.md rename to docs/docs_old/intro.md diff --git a/docs/docs/tutorial-basics/_category_.json b/docs/docs_old/tutorial-basics/_category_.json similarity index 100% rename from docs/docs/tutorial-basics/_category_.json rename to docs/docs_old/tutorial-basics/_category_.json diff --git a/docs/docs/tutorial-basics/congratulations.md b/docs/docs_old/tutorial-basics/congratulations.md similarity index 100% rename from docs/docs/tutorial-basics/congratulations.md rename to docs/docs_old/tutorial-basics/congratulations.md diff --git a/docs/docs/tutorial-basics/create-a-blog-post.md b/docs/docs_old/tutorial-basics/create-a-blog-post.md similarity index 100% rename from docs/docs/tutorial-basics/create-a-blog-post.md rename to docs/docs_old/tutorial-basics/create-a-blog-post.md diff --git a/docs/docs/tutorial-basics/create-a-document.md b/docs/docs_old/tutorial-basics/create-a-document.md similarity index 100% rename from docs/docs/tutorial-basics/create-a-document.md rename to docs/docs_old/tutorial-basics/create-a-document.md diff --git a/docs/docs/tutorial-basics/create-a-page.md b/docs/docs_old/tutorial-basics/create-a-page.md similarity index 100% rename from docs/docs/tutorial-basics/create-a-page.md rename to docs/docs_old/tutorial-basics/create-a-page.md diff --git a/docs/docs/tutorial-basics/deploy-your-site.md b/docs/docs_old/tutorial-basics/deploy-your-site.md similarity index 100% rename from docs/docs/tutorial-basics/deploy-your-site.md rename to docs/docs_old/tutorial-basics/deploy-your-site.md diff --git a/docs/docs/tutorial-basics/markdown-features.mdx b/docs/docs_old/tutorial-basics/markdown-features.mdx similarity index 100% rename from docs/docs/tutorial-basics/markdown-features.mdx rename to docs/docs_old/tutorial-basics/markdown-features.mdx diff --git a/docs/docs/tutorial-extras/_category_.json b/docs/docs_old/tutorial-extras/_category_.json similarity index 100% rename from docs/docs/tutorial-extras/_category_.json rename to docs/docs_old/tutorial-extras/_category_.json diff --git a/docs/docs/tutorial-extras/img/docsVersionDropdown.png b/docs/docs_old/tutorial-extras/img/docsVersionDropdown.png similarity index 100% rename from docs/docs/tutorial-extras/img/docsVersionDropdown.png rename to docs/docs_old/tutorial-extras/img/docsVersionDropdown.png diff --git a/docs/docs/tutorial-extras/img/localeDropdown.png b/docs/docs_old/tutorial-extras/img/localeDropdown.png similarity index 100% rename from docs/docs/tutorial-extras/img/localeDropdown.png rename to docs/docs_old/tutorial-extras/img/localeDropdown.png diff --git a/docs/docs/tutorial-extras/manage-docs-versions.md b/docs/docs_old/tutorial-extras/manage-docs-versions.md similarity index 100% rename from docs/docs/tutorial-extras/manage-docs-versions.md rename to docs/docs_old/tutorial-extras/manage-docs-versions.md diff --git a/docs/docs/tutorial-extras/translate-your-site.md b/docs/docs_old/tutorial-extras/translate-your-site.md similarity index 100% rename from docs/docs/tutorial-extras/translate-your-site.md rename to docs/docs_old/tutorial-extras/translate-your-site.md diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts index 344c456..f910c18 100644 --- a/docs/docusaurus.config.ts +++ b/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/', diff --git a/docs/sidebars.ts b/docs/sidebars.ts index 8c799bc..31aa545 100644 --- a/docs/sidebars.ts +++ b/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; diff --git a/package-lock.json b/package-lock.json new file mode 100644 index 0000000..9c56091 --- /dev/null +++ b/package-lock.json @@ -0,0 +1,6 @@ +{ + "name": "atom-tools", + "lockfileVersion": 3, + "requires": true, + "packages": {} +}