bento-cli 0.8.2

Free program analysis focused on bugs that matter to you.

Find Python web-app bugs delightfully fast, without changing your workflow

Installation · Motivations · Usage · Workflows
Integrations · Bento Checks · Help & Community

Bento is a free bug-finding tool that runs locally when you commit code. It has specialty checks for common Python 3 web frameworks and OSS checks for Python, Docker, and shell files.

• Find bugs that matter. Bento runs its own checks and OSS tools to catch actual bugs. Checks are fine-tuned based on their behavior across thousands of PyPI projects, and Bento never reports style-related issues.
• Keep your workflow. Unlike other tools, you won’t have to fix existing bugs to adopt Bento. Other project contributors won’t see Bento files or have their workflows changed. It’s just for you.
• Go delightfully fast. Bento checks for issues introduced by your new code, as you commit it. Tools run on your machine in parallel, not sequentially.

Installation

$ pip3 install bento-cli

Bento requires Python 3.6+ and Docker 19.03+. It runs on macOS and Linux.

Motivations

See our Bento introductory blog post to learn the full story.

r2c is on a quest to make world-class security and bugfinding available to all developers, for free. We’ve learned that most developers have never heard of—let alone tried—tools that find deep flaws in code: like Codenomicon, which found Heartbleed, or Zoncolan at Facebook, which finds more top-severity security issues than any human effort. These tools find severe issues and also save tons of time, identifying hundreds of thousands of issues before humans can. Bento is a step towards universal access to tools like these.

We’re also big proponents of opinionated tools like Black and Prettier. This has two implications: Bento ignores style-related issues and the bikeshedding that comes with them, and it ships with a curated set of checks that we believe are high signal and bug-worthy. See Three things your linter shouldn’t tell you for more details on our decision making process.

Usage

Getting Started

From the root directory of a project:

$ bento init

This configures Bento for you only. See Team Use to setup Bento for all contributors.

Upgrading

Docker is a requirement for Bento 0.8+.

Run the following commands to upgrade Bento:

$ pip3 install --upgrade bento-cli
$ cd <PROJECT DIRECTORY>
# Use `git rm` and `git commit` if you previously added Bento files to source control:
$ rm -r .bento*
$ bento init

The last line removes all Bento artifacts as their formats have not yet stabalized between releases, including the Bento archive.

For Bento 0.8+ no Bento files need to be tracked with Git unless you’re using Bento in CI. See Running in CI/CD for details.

Command Line Options

$ bento --help
Usage: bento [OPTIONS] COMMAND [ARGS]...

Options:
  -h, --help             Show this message and exit.
  --version              Show the version and exit.
  --base-path DIRECTORY  Path to the directory containing the code, as well as
                         the config.yml file.
  --agree                Automatically agree to terms of service.
  --email TEXT           Email address to use while running this command
                         without global configs e.g. in CI

Commands:
  archive  Suppress current findings.
  check    Checks for new findings.
  disable  Turn OFF a Bento feature for this project.
  enable   Turn ON a Bento feature for this project.
  init     Autodetects and installs tools.

  To get help for a specific command, run `bento COMMAND --help`

Exit Codes

bento check may exit with the following exit codes:

• 0: Bento ran successfully and found no errors
• 2: Bento ran successfully and found issues in your code
• 3: Bento or one of its underlying tools failed to run

Workflows

Individual Use

Bento configures itself for personal use by default. This means that it:

1. Automatically checks for issues introduced by your code, as you commit it
2. Only affects you; it won’t change anything for other project contributors or modify Git state

Initialization enables autorun behind the scenes. By default autorun blocks the commit if Bento returns findings. To make it non-blocking:

$ bento enable autorun --no-block

You can always manually run Bento on staged files or directories via:

$ bento check [PATHS]

This will show only new findings introduced by these files AND that are not in the archive (.bento/archive.json). Use --all to check all Git tracked files, not just those that are staged:

$ bento check --all [PATHS]

This feature makes use of Git hooks. If the Bento hook incorrectly blocks your commit, you can skip it by passing the --no-verify flag to Git at commit-time (please use this sparingly since all hooks will be skipped):

$ git commit --no-verify

Team Use

Running Locally

To setup Bento for all project contributors, add Bento’s configuration to Git (it’s ignored by default):

$ cd <PROJECT DIRECTORY>
$ git add --force .bento .bentoignore

Contributors can run Bento for themselves using the project’s configuration via:

$ bento init

Running in CI/CD

Bento in CI analyzes your entire project, not just the latest commit. So that you don’t have to fix all existing issues before making Bento blocking, its archive feature allows historical issues to be tracked and ignored during CI.

To use the archive feature so Bento returns a non-zero exit code only for new issues, rather than all existing issues, first create the archive:

$ cd <PROJECT DIRECTORY>
$ bento archive .

Commit Bento’s configuration to the project:

$ git add --force .bento .bentoignore

You can then add Bento to your CI scripts:

$ pip3 install bento-cli && bento --version
$ bento --agree --email=<YOUR_EMAIL> check --all 2>&1 | cat

We pipe through cat to disable Bento's interactive tty features (e.g. progress bars, using a pager for many findings).

If you use CircleCI, the above commands become:

version: 2.1

jobs:
  bentoCheck:
  executor: circleci/python:3.7.4-stretch-node
  steps:
    - checkout
    - run:
        name: "Install Bento"
        command: pip3 install bento-cli && bento --version
    - run:
        name: "Run Bento check"
        command: bento --agree --email=<YOUR_EMAIL> check --all 2>&1 | cat

bento check will exit with a non-zero exit code if it finds issues in your code (see Exit Codes).

If you need help setting up Bento with another CI provider please open an issue. Documentation PRs welcome if you set up Bento with a CI provider that isn’t documented here!

Bento Checks

Bento finds common security, correctness, and performance mistakes in projects containing Flask, Requests, and Boto 3. We’re inspired by tools that help ensure correct and safe framework use, like eslint-plugin-react. Learn more about Bento’s specialty checks at checks.bento.dev.

Help and Community

Need help or want to share feedback? We’d love to hear from you!

• Email us at [e-mail]
• Join #bento in our community Slack
• File an issue or submit a feature request directly on GitHub — we welcome them all!

We’re constantly shipping new features and improvements.

• Sign up for the Bento newsletter — we promise not to spam and you can unsubscribe at any time
• See past announcements, releases, and issues here

We’re fortunate to benefit from the contributions of the open source community and great projects such as Bandit, ESLint, Flake8, and their plugins. 🙏

License and Legal

Please refer to the terms and privacy document.

Copyright (c) r2c.

---

Changelog

This project adheres to Semantic Versioning.

0.8.2 - 2020-02-05

Fixed

• bento check works with repos with no previous commits
• Verify a path is a file before checking if it contains a shell shebang (shellcheck tool)
• Correctly install autorun even if git-hooks subdirectory is non-existent

0.8.1 - 2020-01-30

Fixed

• Perfomance improvements when running in large projects
• Additional human readable check_ids for bandit

0.8.0 - 2020-01-24

This release represents a major shift in Bento's default behavior: It emphasizes an incremental and personal, rather than team-wide, workflow that makes Bento a smaller commitment to use:

1. Other project contributors won’t see Bento files or have their workflows changed.

2. You no longer need to manually run Bento. After initialization Bento will automatically check for issues in your code as you commit, analyzing only the files that have changed.

3. You won’t see a project’s old issues (tech debt) during initialization. To view them, run

   bento check --all
   

Migration

Project configurations have changed in version 0.8. In order to migrate a project from version 0.7 or earlier:

• Ensure Bento has been upgraded using pip3 install --upgrade bento-cli. Run bento --version to validate Bento’s version.
• rm -r .bento* (Use git rm if you have previously added Bento files to source control).
• Run bento init in the project root.

New requirements

• Docker must be installed, and the docker client running, to use Bento.

Changed

How you use Bento has changed significantly in 0.8.

Usage changes

• bento check will now only check staged changes.

  • Use bento check --all to check the entire project.

• bento archive will archive findings due to staged diff:

  • Use bento archive --all to archive all findings in a project.

Other changes

• hadolint and shellcheck are now enabled by default.
• Messages for findings are no longer truncated.
• bento init will now install an empty configuration on a project it can not identify; tools may then be manually enabled using bento enable tool TOOL. Use bento enable tool --help to list tools.
• Virtual environments for Python tools are now installed in your home directory, instead of in your project directories.
• eslint is now installed in your project’s .bento directory, and will not modify your project’s package.json.
• Tool and check names have been modified to improve readability.
• eslint is disabled by default. To enable it run bento enable tool eslint.

Added

• On init, Bento will prompt you to ask if you want to add ignore patterns to your global Git ignore file. If you agree, Bento will alter this file to ignore Bento configuration files in your git projects.
• bento enable autorun and bento disable autorun will cause Bento to either begin or stop analyzing code on every commit.
• Tab completion can now be installed by Bento. To install for your shell, run bento enable autocomplete. To remove tab completion, run bento disable autocomplete.

Removed

• bento check --show-all has been removed. Use bento check --all instead. Archived findings can be found at ~/.bento/archive.json.
• bento install-hook has been removed. Use bento enable autorun to run Bento on every commit.
• The histogram formatter is no longer used by default. To show findings with a histogram, run bento check -f histo.

0.7.0 - 2019-12-11

Fixed

• Fixed r2c.hadolint issue where it failed to detect files with .dockerfile suffixes.
• Fixed r2c.sgrep to respect file path when running on specific files with bento check /path/to/file

Changed

• Redesigned bento init
  • It now runs bento check and bento archive itself; these were almost always run manually by users immediately after bento init
  • Displays histogram of results
• bento check supports running a single tool with the -t flag: bento check -t r2c.flask
• Reworked user registration flow
• Removed flake8-builtins plugin from r2c.flask based on user feedback: codebases with SQLAlchemy models (common in Flask apps) regularly shadow the id builtin, causing false positives.
• Added eslint arrow-body-style as a default ignore because it is a style issue.
• Added unused variable/import related checks (eslint no-unused-vars and no-var, flake8 F401 and F841)to default ignore. While useful they are very noisy and are often non-issues.

Added

• Added r2c.boto3 tool for Boto3 framework. To use it on a project, run bento enable tool r2c.boto3
• Added additional checks for r2c.flake8
  • unescaped-file-extension
  • use-jsonify

0.6.2 - 2019-12-05

Fixed

• Fixed an issue where upgrade notifications were not shown to users.
• Fix an issue where certain .gitignore patterns would cause an error or be skipped by Bento
• Properly render multi-line context in the Clippy formatter.

0.6.1 - 2019-11-26

Fixed

• Bento no longer completes initialization if it can't identify a project; this prevents confusing errors when subsequently running bento check.
• Pinned versions of all 3rd-party Python tools, so that remote package upgrades do not break Bento.
• Bento no longer crashes if a project path contains a space.

Changed

• Results of bento check are now printed using the Clippy and histogram formatters (see "Added" section below) by default.
• The APIs to enable and disable a check are now bento enable check [check] and bento disable check [check].
• The r2c.flask tool is now enabled by default. It finds best-practice and security bugs in code using the Python Flask framework.
• Multiple formatters can now be used to display results from bento check. For example, bento check -f stylish -f histo will display results using the Stylish formatter, followed by display using a histogram formatter.
• Progress bars are not emitted to stderr if not a tty; this prevents progress-bar output from littering CI logs.
• Updated progress bar glyphs for readability on a wider range of terminal themes.
• Disabled r2c.flake8 check B001 by default, in favor of the (also included) E722 check.

Added

• Added r2c.requests, which finds best-practice and security bugs in code using the Python Requests framework. It is enabled by default.
• Added r2c.sgrep, a syntactically aware code search tool. It is not enabled by default. To use it on a project, run bento enable tool r2c.sgrep. Note that Docker is required in order to use r2c.sgrep.
• All findings, including those previously archived, can now be viewed using bento check --show-all.
• Tools can now be enabled using bento enable tool [tool_id]. Available tools can be listed by running bento enable tool --help or using shell autocompletion. Tools can be disabled using bento disable tool [tool_id].

0.6.0

Version 0.6.0 was not released.

0.5.0 - 2019-11-18

Fixed

• r2c.eslint now properly detects TypeScript imports.
• r2c.eslint now detects global node environments (e.g., jest), and properly resolves their global variables.

Changed

• To better protect users' data, error messages are no longer reported to our backend.
• .bentoignore can now be configured to include patterns from other files; by default the contents of the project's .gitignore are included. For more information, please see the comments at the top of the generated .bentoignore file.
• Tab completion times reduced by approximately half.
• Disabled a number of r2c.eslint checks by default:
  • arrow-parens, as it conflicts with Prettier's default behavior.
  • TypeScript semicolon checking, which is stylistic.
  • import/no-cycle which takes 50% of tool runtime on moderately large code bases.
• r2c.flake8 E306 disabled by default, as it is stylistic in nature.
• Runtime of r2c.eslint has been reduced by up to 30% for some projects.

Added

• Added r2c.shellcheck tool for shell scripts. To enable, add r2c.shellcheck to the tools section of your .bento.yml. Note that this tool requires docker as a dependency.
• Added r2c.hadolint tool for Docker files. To enable, add r2c.hadolint to the tools section of your .bento.yml. Note that this tool requires docker to be installed in order to run.

0.4.1 - 2019-11-14

Fixed

• Fixes a performance regression due to changes in metrics collection.

0.4.0 - 2019-11-11

Changed

• We updated our privacy policy.
  • Notably, we collect email addresses to understand usage and communicate with users through product announcements, technical notices, updates, security alerts, and support messages.

Added

• Added additional r2c.click tool for Click framework:

  • flake8-click will be disabled by default.

• Added additional r2c.flask tool for Flask framework:

  • flake8-flask will be disabled by default.

0.3.1 - 2019-11-08

Fixed

• Fixed an issue where the tool would fail to install if a macOS user had installed gcc and then upgraded their OS.
• Fixed a compatibility issue for users with a pre-existing version of GitPython with version between 2.1.1 and 2.1.13.

0.3.0 - 2019-11-01

Changed

• Bento can now be run from any subdirectory within a project.
• Updated the privacy and terms-of-service statement.

Added

• File ignores are configurable via git-style ignore patterns (include patterns are not supported). Patterns should be added to .bentoignore.

• Added additional checks to the r2c.flake8 tool:

  • All checks from flake8-bugbear (except for B009 and B010, which are stylistic in nature).
  • All checks from flake8-builtins.
  • All checks from flake8-debugger.
  • All checks from flake8-executable.

• Clippy output formatting is now supported.

  • To enable, run: bento check --formatter clippy
  • Example output:

error: r2c.flake8.E113
   --> foo.py:6:5
    |
  6 |   return x
    |
    = note: unexpected indentation

• Autocompletion is now supported from both bash and zsh. To use:
  • In bash, run echo -e '\neval "$(_BENTO_COMPLETE=source bento)"' >> ~/.bashrc.
  • In zsh, run echo -e '\neval "$(_BENTO_COMPLETE=source_zsh bento)"' >> ~/.zshrc.

0.2.1 - 2019-10-29

Fixed

• Quoted emails in git configuration do not break user registration.
• Removed files properly invalidate results cache.
• Python tools do not crawl node_modules.

0.2.0 - 2019-10-23

Changed

• Results are cached between runs. This means that an immediate rerun of bento will be much faster.
• Broadened library compatibility, especially for common packages:
  • attrs from 18.2.0
  • packaging from 14.0
  • pre-commit from 1.0.0
• r2c.eslint ignores .min.js files. Bento should only report issues in code, not built artifacts.
• Telemetry endpoint uses bento.r2c.dev.

Added

• Bento check will optionally run only on passed paths, using bento check [path] ....
• Add r2c.pyre as a configurable tool. To enable, it must be manually configured in .bento.yml.
• Formatters can be specified with short names, and these appear in the help text. For example, bento check --formatter json.
• bento version is passed to telemetry backend.

Fixed

• Tool does not crash if a git user does not have an email configured.
• Fixed a regression that caused progress bars to hang after first tool completed.
• Made fully compatible with Python 3.6.
• Tool does not mangle .gitignore when that file lacks a trailing newline.