Skip to content

Commit

Permalink
Merge 1999900 into 946343e
Browse files Browse the repository at this point in the history
  • Loading branch information
@dmuhs
dmuhs authored Feb 10, 2020
2 parents 946343e + 1999900 commit 853d845
Show file tree
Hide file tree
Showing 12 changed files with 347 additions and 113 deletions.
15 changes: 8 additions & 7 deletions docs/advanced-usage.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,9 +24,9 @@ functionality encapsulates all targets passed to the :code:`analyze` subcommand.

A short example:

.. code::
.. code-block:: console
mythx analyze --create-group dir1/ test.sol test2.sol
$ mythx analyze --create-group dir1/ test.sol test2.sol
This command will initialize an empty group, add all analyses coming from :code:`dir1/`
and the two test Solidity files into it, and close it once submission has been completed.
Expand Down Expand Up @@ -100,9 +100,10 @@ IDs could also be stored in a file as a CI artifact and later retrieved by anoth
e.g. to kickstart a security or QA pipeline.

An example is the submission of a large truffle project:
.. code::

mythx analyze --async my-project/
.. code-block:: console
$ mythx analyze --async my-project/
This flag is also best friends with the :code:`--create-group` flag for the :code:`analyze` subcommand. Together
they help keeping the MythX dashboard overview tidy.
Expand All @@ -126,9 +127,9 @@ The filtering options can be freely combined with the :code:`--ci` flag to achie
A simple example is excluding the (fairly common) floating pragma issue type, and assert and requirement
violations for testing purposes:

.. code::
.. code-block:: console
mythx --ci analyze --swc-blacklist 110,123,103 my-project/
$ mythx --ci analyze --swc-blacklist 110,123,103 my-project/
Custom Report Rendering
Expand All @@ -148,7 +149,7 @@ Writing a New Template From Scratch

Is the default layout too complex? Do block names confuse you? No worries! The MythX CLI of course
also support completely user-defined templates. These templates can be specified using
`Jinja2 <https://jinja.palletsprojects.com/>`_. With basic knowledge of HTML, CSS, Jinja, and
`the Jinja2 syntax <https://jinja.palletsprojects.com/>`_. With basic knowledge of HTML, CSS, Jinja, and
possibly also JavaScript (if you feel fancy), it is fairly easy to write a template. Explaining the
inner workings of Jinja and the core principles of web design are out of scope for this section.
It is relevant to know what context MythX provides for user-defined templates. There are two core
Expand Down
133 changes: 105 additions & 28 deletions docs/usage.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ Basic MythX services are free of charge.
No payment information or email address are required and you can start
using MythX right away by signing up for an account `here <https://dashboard.mythx.io/#/registration>`_.
Once set up, head over to the `dashboard <https://dashboard.mythx.io/>`_.
In the *Profile* section various means of authentication are presented.
In the *Tools* section various means of authentication are presented.


Using API Tokens
Expand Down Expand Up @@ -70,33 +70,34 @@ Submitting Analyses
$ mythx analyze --help
Usage: mythx analyze [OPTIONS] [TARGET]...
Analyze the given directory or arguments with MythX.
Analyze the given directory or arguments with MythX.
Options:
--async / --wait Submit the job and print the UUID, or wait for
execution to finish
--mode [quick|full] [default: quick]
--create-group Create a new group for the analysis
--group-id TEXT The group ID to add the analysis to
--group-name TEXT The group name to attach to the analysis
--min-severity TEXT Ignore SWC IDs below the designated level
--swc-blacklist TEXT A comma-separated list of SWC IDs to ignore
--swc-whitelist TEXT A comma-separated list of SWC IDs to include
--solc-version TEXT The solc version to use for compilation
--help Show this message and exit.
--async / --wait Submit the job and print the UUID, or wait for
execution to finish
--mode [quick|standard|deep] [default: quick]
--create-group Create a new group for the analysis
--group-id TEXT The group ID to add the analysis to
--group-name TEXT The group name to attach to the analysis
--min-severity TEXT Ignore SWC IDs below the designated level
--swc-blacklist TEXT A comma-separated list of SWC IDs to ignore
--swc-whitelist TEXT A comma-separated list of SWC IDs to include
--solc-version TEXT The solc version to use for compilation
--help Show this message and exit.
Submit a new analysis to the MythX API.
This command works in different scenarios, simply by calling :code:`mythx analyze`:
This command works in different scenarios, simply by calling :code:`mythx analyze`,
optionally on a target directory or file:

1. Either :code:`truffle-config.js` or :code:`truffle.js` are found in the
directory. In this case, the MythX CLI checks the
:code:`<project_dir>/build/contracts` path for artifact JSON files
target directory or current working directory. In this case, the MythX CLI
checks the :code:`<project_dir>/build/contracts` path for artifact JSON files
generated by the :code:`truffle compile` command. For each artifact found
a new job is submitted to the MythX API.
2. If no Truffle project can be detected, the MythX CLI will automatically
enumerate all Solidity files (having the :code:`.sol` extension) in the
current directory and all subdirectories.
current or target directory and all its subdirectories.
A prompt will be displayed asking the user to confirm the submission of
the number of smart contracts found.
This is done to make sure a user does not accidentally submit a huge
Expand All @@ -120,20 +121,27 @@ submitted to the MythX API.
This will increase the number of detected issues (as e.g. symbolic execution
tools in the MythX backend can pick up on the bytecode), as well as reduce
the number of false positive issues. The MythX CLI will try to infer the
:code:`solc` version based on the pragma set in the source code.
:code:`solc` version based on the pragma set in the source code. An explicit
compiler version can be specified with the :code:`--solc-version` flag.


Fetching the Analysis Status
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: console
$ mythx analysis status --help
Usage: mythx analysis status [OPTIONS] [UUIDS]...
Get the status of an already submitted analysis.
Options:
--help Show this message and exit.
--help Show this message and exit.
This subcommand prints the status of an already submitted analysis.::
This subcommand prints the status of an already submitted analysis.

.. code-block:: console
$ mythx --format=simple analysis status 381eff48-04db-4f81-a417-8394b6614472
UUID: 381eff48-04db-4f81-a417-8394b6614472
Expand All @@ -150,10 +158,17 @@ Fetching Analysis Reports

.. code-block:: console
$ mythx analysis report --help
Usage: mythx analysis report [OPTIONS] [UUIDS]...
Fetch the report for a single or multiple job UUIDs.
Options:
--help Show this message and exit.
--min-severity [low|medium|high]
Ignore SWC IDs below the designated level
--swc-blacklist TEXT A comma-separated list of SWC IDs to ignore
--swc-whitelist TEXT A comma-separated list of SWC IDs to include
--help Show this message and exit.
This subcommand prints the report of one or more finished analyses in the
Expand Down Expand Up @@ -183,7 +198,9 @@ The :code:`simple` format option will also resolve the report's source map
locations to the corresponding line and column numbers in the Solidity
source file.
This is only possible if the user has specified the source map in their
request and is passing the Solidity source code as text.::
request and is passing the Solidity source code as text.

.. code-block:: console
$ mythx --format=simple analysis report ab9092f7-54d0-480f-9b63-1bb1508280e2
UUID: ab9092f7-54d0-480f-9b63-1bb1508280e2
Expand All @@ -200,11 +217,16 @@ Listing Past Analyses

.. code-block:: console
$ mythx analysis list --help
Usage: mythx analysis list [OPTIONS]
Get a list of submitted analyses.
Options:
--number INTEGER RANGE The number of most recent analysis jobs to display
--help Show this message and exit.
--number INTEGER RANGE The number of most recent analysis jobs to display
[default: 5]
--help Show this message and exit.
This subcommand lists the past analyses associated to the current user.

Expand All @@ -219,7 +241,9 @@ the MythX CLI will automatically query the next page until the desired
number is reached.

To prevent too many network requests, the maximum number of analyses
that can be fetched it capped at 100.::
that can be fetched it capped at 100.

.. code-block:: console
$ mythx analysis list
╒══════════════════════════════════════╤══════════╤═════════════════╤══════════════════════════════════╕
Expand All @@ -240,6 +264,7 @@ The Grouping Functionality

.. code-block:: console
$ mythx group --help
Usage: mythx group [OPTIONS] COMMAND [ARGS]...
Create, modify, and view analysis groups.
Expand All @@ -261,6 +286,17 @@ the `MythX dashboard overview <https://dashboard.staging.mythx.io/#/console/anal
Opening Groups
~~~~~~~~~~~~~~

.. code-block:: console
$ mythx group open --help
Usage: mythx group open [OPTIONS] [NAME]
Create a new group to assign future analyses to.
Options:
--help Show this message and exit.
To open a new group, simply type:

.. code-block:: console
Expand All @@ -277,7 +313,7 @@ Adding Analyses to a Group
To analyze a sample, simply pass the group ID (and optionally the name)
as parameters to the :code:`mythx analyze` call:

.. code-block::
.. code-block:: console
$ mythx analyze --group-name "super important" --group-id 5df7c8932a73230011271d27 --async fallout.sol remythx-mbt385.sol token.sol functiontypes-swc127.sol
Expand All @@ -292,6 +328,17 @@ MythX Dashboard:
Closing Groups
~~~~~~~~~~~~~~

.. code-block:: console
$ mythx group close --help
Usage: mythx group close [OPTIONS] IDENTIFIERS...
Close/seal an existing group.
Options:
--help Show this message and exit.
After all data has been submitted, the group must be closed again:

.. code-block:: console
Expand All @@ -305,6 +352,17 @@ MythX analysis groups will always stay open until explicitly closed.
Fetching the Group Status
~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: console
$ mythx group status --help
Usage: mythx group status [OPTIONS] [GIDS]...
Get the status of an analysis group.
Options:
--help Show this message and exit.
.. code-block:: console
$ mythx group status 5e0f761d5171cc001109dd18
Expand Down Expand Up @@ -351,6 +409,19 @@ that have been found once the analysis is completed.
Listing Groups
~~~~~~~~~~~~~~

.. code-block:: console
$ mythx group list --help
Usage: mythx group list [OPTIONS]
Get a list of analysis groups.
Options:
--number INTEGER RANGE The number of most recent groups to display
[default: 5]
--help Show this message and exit.
.. code-block:: console
$ mythx group list
Expand All @@ -369,7 +440,9 @@ Format Options
--------------

A format option is passed to the :code:`--format` option of the
:code:`mythx` root command. E.g.::
:code:`mythx` root command. E.g.:

.. code-block:: console
$ mythx --format json-pretty analysis report ab9092f7-54d0-480f-9b63-1bb1508280e2
Expand All @@ -395,6 +468,7 @@ API Version Information

.. code-block:: console
$ mythx version --help
Usage: mythx version [OPTIONS]
Options:
Expand All @@ -409,7 +483,9 @@ removed, and additional helpful data can be returned.

The MythX team has included a hash of all versions so changes are easily
noticed simply by comparing the hash an analysis has run under with the one
returned by the API.::
returned by the API.

.. code-block:: console
$ mythx version
API: v1.4.34.4
Expand All @@ -427,6 +503,7 @@ Rendering Reports

.. code-block:: console
$ mythx render --help
Usage: mythx render [OPTIONS] TARGET
Render an analysis job or group report as HTML.
Expand Down
Loading

0 comments on commit 853d845

Please sign in to comment.