README.md in inspec_tools-1.2.2 vs README.md in inspec_tools-1.3.0

- old
+ new

@@ -1,38 +1,32 @@ # InspecTools -InspecTools supplies several CLI tools to convert to and from InSpec format. The converters in version 0.2 are: +InspecTools supplies several CLI tools to convert to and from InSpec format. -* compliance -* summary -* csv2inspec -* inspec2csv -* xccdf2inspec -* inspec2xccdf -* inspec2ckl -* pdf2inspec +The inspec_tools support the following modules: +- compliance +- summary +- csv2inspec +- inspec2csv +- xccdf2inspec +- inspec2xccdf +- inspec2ckl +- pdf2inspec + It also includes an API that can be used in a ruby application. The Ruby API is defined in lib/inspec_tools/inspec.rb # Installation -Ensure happymapper is not installed, as it will take precedence over nokogiri-happymapper. +Ensure `happymapper` is not installed, as it will take precedence over `nokogiri-happymapper`. Add this line to your application's Gemfile: ``` -gem 'inspec_tools', :git => "https://github.com/mitre/inspec_tools" +gem 'inspec_tools' ``` -And then execute: - - $ bundle - -Clone the repo and install it yourself as: - - $ gem install inspec_tools - # Usage ## Ruby Usage The gem exposes methods for converting from an InSpec results JSON to three formats: CKL, XCCDF, and CSV. In the ruby file add a require statement: @@ -58,16 +52,15 @@ ## Command line Usage On the Command Line, `inspec_tools help` will print a listing of all the command with a short description. For detailed help on any command, run `inspec_tools help [COMMAND]`. Help can also be called with the `-h, --help` flags after any command, like `inspec_tools xccdf2inspec -h`. - ## compliance - compliance parses an inspec results json to check if the compliance level meets a specified threshold. +compliance parses an inspec results json to check if the compliance level meets a specified threshold. - If the specified threshold is not met, an error code (1) is returned along with non-compliant elements. +If the specified threshold is not met, an error code (1) is returned along with non-compliant elements. ``` USAGE: inspec_tools compliance [OPTIONS] -j <inspec-json> -i <threshold-inline> inspec_tools compliance [OPTIONS] -j <inspec-json> -f <threshold-file> FLAGS: @@ -79,39 +72,40 @@ inspec_tools compliance -j examples/sample_json/rhel-simp.json -i '{compliance.min: 80, failed.critical.max: 0, failed.high.max: 0}' inspec_tools compliance -j examples/sample_json/rhel-simp.json -f examples/sample_yaml/threshold.yaml ``` - ##### Possible In-line and yaml file threshold definition styles: -```# ----------------------- + +``` failed: critical: max: 0 high: max: 1 compliance: min: 81 +``` ``` -``` {compliance: {min: 80}, failed: {critical: {max: 0}, high: {max: 0}}} ``` ``` {compliance.min: 81, failed.critical.max: 10, failed.high.max: 0} ``` + ``` compliance.min: 81 failed.critical.max: 10 failed.high.max: 1 ``` ## summary - summary parses an inspec results json to create a summary json - +summary parses an inspec results json to create a summary json + ``` USAGE: inspec_tools summary [OPTIONS] -j <inspec-json> -o <summary-csv> FLAGS: -j --inspec-json <inspec-json> : path to InSpec results Json @@ -120,14 +114,14 @@ Examples: inspec_tools summary -j examples/sample_json/rhel-simp.json -o summary.json ``` - ## xccdf2inspec xccdf2inspec translates an xccdf file to an InSpec profile in one or many files + ``` USAGE: inspec_tools xccdf2inspec [OPTIONS] -x <xccdf-file> FLAGS: -x --xccdf <xccdf-file> : path to the disa stig xccdf file @@ -141,10 +135,11 @@ ``` ## inspec2xccdf inspec2xccdf converts an InSpec profile in json format to a STIG XCCDF Document + ``` USAGE: inspec_tools inspec2xccdf [OPTIONS] -j <inspec-json> -a <xccdf-attr-yml> -o <xccdf-xml> FLAGS: -j --inspec-json <inspec-json> : path to InSpec Json file created using command 'inspec json <profile> > example.json' @@ -156,10 +151,11 @@ ``` ## csv2inspec Convert a csv export of STIG controls to an InSpec profile + ``` USAGE: inspec_tools csv2inspec [OPTIONS] -c <stig-csv> -m <map-yml> FLAGS: -c --csv <stig-csv> : path to DISA Stig style csv @@ -173,17 +169,19 @@ ``` ### generate_map This command will generate a `mapping.xml` file that can be passed in to the `csv2inspec` command with the `--m` option. + ``` USAGE: inspec_tools generate_map ``` ## inspec2csv Convert an InSpec json to a csv file + ``` USAGE: inspec_tools inspec2csv [OPTIONS] -j <inspec-json> -o <profile-csv> FLAGS: -j --inspec-json <inspec-json> : path to InSpec json file @@ -223,40 +221,70 @@ -d --debug : debug run [optional] example: inspec_tools pdf2inspec -p benchmark.pdf -o /path/to/myprofile -f ruby -s true ``` -## version +## version Prints out the gem version ``` USAGE: inspec_tools version ``` -# Development +# Development / PR process + This gem was developed using the [CLI Template](https://github.com/tongueroo/cli-template), a generator tool that builds a starter CLI project. +## A complete PR should include 7 core elements: + +- A signed PR ( aka `git commit -a -s` ) +- Code for the new functionality +- Updates to the CLI +- New unit tests for the functionality +- Updates to the docs and examples in `README.md` and `./docs/*` +- (if needed) Example / Template files ( `metadata.yml`,`example.yml`, etc ) + - Scripts / Scaffolding code for the Example / Template files ( `generate_map` is an example ) +- Example Output of the new functionality if it produces an artifact + +1. open an issue on the main inspec_tools website noting the issues your PR will address +2. fork the repo +3. checkout your repo +4. cd to the repo +5. git co -b `<your_branch>` +6. bundle install +7. `hack as you will` +8. test via rake +9. ensure unit tests still function and add unit tests for your new feature +10. add new docs to the `README.md` and to `./docs/examples` +11. update the CLI as needed and add in `usage` example +12. (if needed) create and document any example or templates +13. (if needed) create any supporing scripts +14. (opt) gem build inspec_tools.gemspec +15. (opt) gem install inspec_tools +16. (opt) test via the installed gem +17. git commit -a -s `<your_branch>` +18. Open a PRs aginst the MITRE inspec_tools repo + +# Testing + There are a set of unit tests. Run `rake test` to run the tests. -To release a new version, update the version number in `version.rb` according to the [Semantic Versioning Policy](https://semver.org/). Then, run `bundle exec rake release` which will create a git tag for the specified version, push git commits and tags, and push the `.gem` file to [github.com](https://github.com/mitre/inspec_tools). +To release a new version, update the version number in `version.rb` according to the [Semantic Versioning Policy](https://semver.org/). +Then, run `bundle exec rake release` which will create a git tag for the specified version, push git commits and tags, and push the `.gem` file to [github.com](https://github.com/mitre/inspec_tools). + ### NOTICE © 2018 The MITRE Corporation. -Approved for Public Release; Distribution Unlimited. Case Number 18-3678. +Approved for Public Release; Distribution Unlimited. Case Number 18-3678. ## NOTICE + MITRE hereby grants express written permission to use, reproduce, distribute, modify, and otherwise leverage this software to the extent permitted by the licensed terms provided in the LICENSE.md file included with this project. -### NOTICE - -This software was produced for the U. S. Government under Contract Number HHSM-500-2012-00008I, and is subject to Federal Acquisition Regulation Clause 52.227-14, Rights in Data-General. - -No other use other than that granted to the U. S. Government, or to those acting on behalf of the U. S. Government under that Clause is authorized without the express written permission of The MITRE Corporation. - -For further information, please contact The MITRE Corporation, Contracts Management Office, 7515 Colshire Drive, McLean, VA 22102-7539, (703) 983-6000. - ### NOTICE -DISA STIGs are published by DISA IASE, see: https://iase.disa.mil/Pages/privacy_policy.aspx +This software was produced for the U. S. Government under Contract Number HHSM-500-2012-00008I, and is subject to Federal Acquisition Regulation Clause 52.227-14, Rights in Data-General. + +No other use other than that granted to the U. S. Government, or to those acting on behalf of the U. S. Government under that Clause is authorized without the express written permission of The MITRE Corporation.DISA STIGs are published by DISA IASE, see: https://iase.disa.mil/Pages/privacy_policy.aspx