How consensysdiligence/mythx-cli works
1. Repository purpose
- This is a Python 3.6+ command-line client for the MythX smart-contract security analysis API.
- It is a thin orchestration layer around the MythX/PythX interaction model: collect user input, submit or query analyses, and render results in multiple output formats.
2. Primary boundary: local CLI vs external API
- The main architectural boundary is between the local CLI process and the remote MythX service.
- Local code handles argument parsing, file discovery, input normalization, report formatting, and HTML rendering.
- Remote calls are delegated through the PythX ecosystem to MythX endpoints for analyses, groups, reports, and version info.
3. CLI entrypoint and command routing
- mythx_cli/cli.py is the top-level command surface exposed as mythx.
- The repository is organized into subcommands, each with its own module tree:
- analyze
- analysis
- group
- render
- version
- This separation makes each command independently testable and keeps remote API actions isolated by domain.
4. Authentication, configuration, and execution options
- The CLI accepts API credentials, username/password, config file, output target, and format flags.
- The runtime also supports CI-oriented behavior such as failing with a non-zero exit code when high-severity findings are present.
- These cross-cutting options affect all major commands and are likely resolved centrally before command execution.
5. Analyze subsystem: building submission payloads
- mythx_cli/analyze/ is responsible for turning local project inputs into analysis submissions.
- It contains specialized handlers for different project types:
- solidity.py for Solidity source inputs
- truffle.py for Truffle project artifacts
- scribble.py for Scribble-related handling
- command.py as the command-level orchestration
- util.py for shared helpers
- This subsystem is the input-preparation layer before data is sent to MythX.
6. Analysis subsystem: querying submitted jobs
- mythx_cli/analysis/ provides read-only operations over existing analyses:
- listing analyses
- fetching a specific report
- checking analysis status
- Conceptually, this is the “monitoring and retrieval” side of the workflow after a submission has been created.
7. Group subsystem: lifecycle management for analysis groups
- mythx_cli/group/ manages groups of analyses:
- open/create
- list
- close
- status
- This indicates that the tool treats analysis groups as first-class remote resources, separate from individual analysis jobs.
8. Rendering and report presentation
- mythx_cli/render/ turns API results into human-consumable HTML or markdown-like output.
- The templates/ directory contains layout and theme variants (default, aesthetic, HTML/MD layouts), so rendering is template-driven rather than hard-coded.
- This subsystem is distinct from formatting: it produces richer report artifacts, likely for sharing or offline review.
9. Formatter subsystem: terminal/file output shapes
- mythx_cli/formatter/ handles output representations for CLI responses:
- simple_stdout
- json
- tabular
- The CLI supports both machine-readable and human-readable views, and the formatter layer sits between API response objects and final output destinations.
- The presence of formatter/util.py and base.py suggests a common abstraction for consistent rendering across commands.
10. Version command as a lightweight API probe
- mythx_cli/version/ exposes a version/info command that likely queries service or client version metadata.
- This is a small but separate command group, which keeps informational API access out of the analysis flows.
11. Data flow through the system
- Typical flow is: user invokes CLI → command module parses inputs → optional project-specific analyzers gather and sanitize source data → MythX request is sent via PythX-backed API integration → response is transformed by formatter or renderer → output goes to stdout, file, or HTML artifact.
- The same response data can be presented in several shapes, which is why output formatting is a distinct subsystem.
12. Quality, testing, and documentation boundaries
- The repo includes a fairly complete tests/ suite with command-specific fixtures and golden output files, which suggests behavior is validated by CLI contract and response formatting.
- Documentation is extensive (docs/ plus ReadTheDocs config), indicating that usage, command behavior, and response formats are part of the public architecture.
- Packaging and release tooling (setup.py, requirements*.txt, CI configs, tox) show this is a distributable Python CLI rather than a long-running service.
Main entry points: cli.py mythx · analyze/command.py Analyze · base.py Formatters · render/command.py Render
Components 23
CLI Core
Entry point, shared options, and command routing.
Analysis Flow
Submission, retrieval, and group lifecycle commands.
- Analyze · Orchestrates analysis submission from local inputs.
mythx_cli/analyze/command.py - Solidity · Builds analysis payloads from Solidity sources.
mythx_cli/analyze/solidity.py - Truffle · Collects and normalizes Truffle project artifacts.
mythx_cli/analyze/truffle.py - Scribble · Handles Scribble-related analysis preparation.
mythx_cli/analyze/scribble.py - List · Lists submitted analyses.
mythx_cli/analysis/list.py - Report · Fetches a specific analysis report.
mythx_cli/analysis/report.py - Status · Checks analysis execution status.
mythx_cli/analysis/status.py - Open · Creates or opens an analysis group.
mythx_cli/group/open.py - Group List · Lists analysis groups.
mythx_cli/group/list.py - Close · Closes an analysis group.
mythx_cli/group/close.py - Group Status · Checks the state of an analysis group.
mythx_cli/group/status.py - Version · Queries client or service version metadata.
mythx_cli/version/command.py
Output
Formatters and report rendering.
- Render · Produces HTML or markdown-style report artifacts.
mythx_cli/render/command.py - Templates · HTML and MD layout/theme templates.
mythx_cli/render/templates - Formatters · Shared output abstraction for CLI responses.
mythx_cli/formatter/base.py - JSON · Machine-readable JSON output.
mythx_cli/formatter/json.py - Stdout · Simple human-readable terminal output.
mythx_cli/formatter/simple_stdout.py - Tabular · Table-shaped CLI output.
mythx_cli/formatter/tabular.py
Remote Service
Integration boundary to MythX via PythX.
- PythX · Client boundary used to talk to MythX endpoints.
- MythX API · External analysis, group, report, and version service.
Validation
Tests and contract fixtures.
- Tests · Contract and formatting regression tests with fixtures.
tests
Connections 32
- mythx → Options: reads options · CLI resolves credentials, config, and runtime flags before dispatch.
- mythx → Analyze: routes · Dispatches analyze subcommands.
- mythx → List: routes · Dispatches analysis queries.
- mythx → Open: routes · Dispatches group commands.
- mythx → Render: routes · Dispatches rendering commands.
- mythx → Version: routes · Dispatches version/info command.
- Analyze → Solidity: prepares · Uses Solidity-specific input handling.
- Analyze → Truffle: prepares · Uses Truffle project handling.
- Analyze → Scribble: prepares · Uses Scribble-specific preparation.
- Solidity → PythX: submits · Builds and submits analysis payloads through the client layer.
- Truffle → PythX: submits · Builds and submits project-derived payloads through the client layer.
- Scribble → PythX: submits · Feeds annotated inputs into the client layer.
- List → PythX: queries · Fetches analysis listings from the remote service.
- Report → PythX: queries · Fetches report details from the remote service.
- Status → PythX: queries · Checks analysis status remotely.
- Open → PythX: mutates · Creates or opens remote groups.
- Group List → PythX: queries · Lists remote groups.
- Close → PythX: mutates · Closes remote groups.
- Group Status → PythX: queries · Checks group status remotely.
- Version → PythX: queries · Retrieves version metadata from the service or client boundary.
- Render → Templates: uses · Renders reports through template variants.
- Render → MythX API: formats · Turns API results into offline-friendly artifacts.
- Formatters → JSON: implements · Shared abstraction for JSON output.
- Formatters → Stdout: implements · Shared abstraction for terminal output.
- Formatters → Tabular: implements · Shared abstraction for tabular output.
- JSON → PythX: presents · Shapes remote response objects for machine consumers.
- Stdout → PythX: presents · Shapes remote response objects for humans.
- Tabular → PythX: presents · Shapes remote response objects into tables.
- PythX → MythX API: calls · Client library boundary to MythX endpoints.
- Tests → mythx: covers · Validates command behavior and CLI contracts.
- Tests → Formatters: covers · Validates output formatting and rendering.
- Tests → Render: covers · Validates report rendering and templates.