Permalink
Browse files

update readme and add contributing section

TelekomLabs-DCO-1.1-Signed-off-by: Edmund Haselwanter <me@ehaselwanter.com> (github: ehaselwanter)
  • Loading branch information...
ehaselwanter committed Dec 8, 2014
1 parent ba8a052 commit d0b8a2a5abf5816c35b4ffc52d4854ee95c31edc
Showing with 161 additions and 9 deletions.
  1. +88 −0 CONTRIBUTING.md
  2. +73 −9 README.md
View
@@ -0,0 +1,88 @@
# Contributor Guideline
This document provides an overview of how you can participat in improving this project or extending it. We are grateful for all your help: bug reports and fixes, code contributions, documentation or ideas. Feel free to join, we appreciate your support!!
## Communication
### GitHub repositories
Much of the issues, goals and ideas are tracked in the respective projects in GitHub. Please use this channel to report bugs and post ideas.
### Trello
The overall hardening project is organized publicly on Trello. Feel free to join and add tasks and ideas for the overall project. [https://trello.com/b/gL9v8N1q/dt-hardening](https://trello.com/b/gL9v8N1q/dt-hardening)
## git and GitHub
In order to contribute code please:
1. Fork the project on GitHub
2. Clone the project
3. Add changes (and tests)
4. Commit and push
5. Create a merge-request
To have your code merged, see the expectations listed below.
You can find a well-written guide [here](https://help.github.com/articles/fork-a-repo).
Please follow common commit best-practices. Be explicit, have a short summary, a well-written description and references. This is especially important for the merge-request.
Some great guidelines can be found [here](https://wiki.openstack.org/wiki/GitCommitMessages) and [here](http://robots.thoughtbot.com/5-useful-tips-for-a-better-commit-message).
## Expectations
### Don't reinvent the wheel
This hardening project doesn't intend to reinvent the configuration stack for services. Aim to use official configuration projects first and provide hardening as a layer on top. The goal is remove the need for a user to configure all aspects of services and maintain security configuration. This way, the user can still configure a service using the interface provided by the official project.
* For Chef refer to the official [opscode community cookbooks](http://community.opscode.com/cookbooks).
* For Puppet head to the [Puppet Forge](https://forge.puppetlabs.com/) and take a node of the Puppet supported modules.
These projects are generally hosted on GitHub as well.
In some cases, we in fact create the full rollout stack, but this is generally the exception ([os-hardening](https://github.com/TelekomLabs/chef-os-hardening), [nginx-hardening](https://github.com/TelekomLabs/chef-nginx-hardening)).
### Be explicit
* Please avoid using nonsensical property and variable names
* Use self-describing attribute names for user configuration
* In case of failures, communicate what happened and why a failure occurs to the user. Make it easy to track the code or action that produced the error. Try to catch and handle errors if possible to provide improved failure messages.
### Add tests
The security review of this project is done using integration tests.
Whenever you add a new security configuration, please start by writing a test that checks for this configuration. For example: If you want to set a new attribute in a configuration file, write a test that expects the value to be set first. Then implement your change.
You may add a new feature request by creating a test for whatever value you need.
All tests will be reviewed internally for their validity and overall project direction.
### Document your code
As code is more often read than written, please provide documentation in all projects.
Adhere to the respective guidelines for documentation:
* Chef generally documents code based explicit readme files. For code documentation please use [yard-chef](https://github.com/rightscale/yard-chef)
* [Puppet module documentation](http://docs.puppetlabs.com/puppet/latest/reference/modules_documentation.html)
### Follow coding styles
We generally include test for coding guidelines:
* Chef follows [Foodcritic](http://acrmp.github.io/foodcritic/)
* Puppet is checked with [puppet-lint](http://puppet-lint.com/checks/)
Remember: Code is generally read much more often than written.
### Use Markdown
Wherever possible, please refrain from any other formats and stick to simple markdown.
View
@@ -11,23 +11,87 @@ This cookbook provides a secure overlay for apache configuration.
## Requirements
* Opscode chef
* chef
## Attributes
## Usage
... wip ...
A sample role may look like:
## Usage
```json
{
"name": "apache",
"default_attributes": { },
"override_attributes": { },
"json_class": "Chef::Role",
"description": "Apache Hardened Server Test Role",
"chef_type": "role",
"run_list": [
"recipe[apt]",
"recipe[apache2]",
"recipe[apache-hardening]"
]
}
```
## Recipes
### apache-hardening::hardening (default)
This recipe is an overlay recipe for the [apache2 cookbook](https://github.com/viverae-cookbooks/apache2) and applies `apache-hardening::hardening`
Add the following to your runlist and customize security option attributes
```
"recipe[apache2]",
"recipe[apache-hardening]"
```
This hardening recipe installs the hardening but expects an existing installation of Apache2.
## Security Options
* `node['apache']['traceenable'] = 'Off'`
This directive overrides the behavior of TRACE for both the core server and mod_proxy.
See [http://httpd.apache.org/docs/2.2/mod/core.html#traceenable](http://httpd.apache.org/docs/2.2/mod/core.html#traceenable) for details
Defaults to: `Off`
* `node['apache_hardening']['allowed_http_methods'] = %w( GET POST )`
A list of HTTP methods that should be allowed in the server.
See [http://httpd.apache.org/docs/trunk/mod/mod_allowmethods.html](http://httpd.apache.org/docs/trunk/mod/mod_allowmethods.html) for details
Defaults to: `GET POST`
* `node['apache_hardening']['modules_to_disable'] = %w( cgi cgid )`
This parameter sets a list of modules that should be disabled on the target server.
See [http://httpd.apache.org/docs/current/mod/](http://httpd.apache.org/docs/current/mod/) for details
Defaults to: `cgi cgid`
## Tests
```
# Install dependencies
gem install bundler
bundle install
# Do lint checks
bundle exec rake lint
# Fetch tests
bundle exec thor kitchen:fetch-remote-tests
... wip ...
# fast test on one machine
bundle exec kitchen test default-ubuntu-1204
## FAQ / Pitfalls
# test on all machines
bundle exec kitchen test
... wip ...
# for development
bundle exec kitchen create default-ubuntu-1204
bundle exec kitchen converge default-ubuntu-1204
```
## Contributors + Kudos
... wip ...
* Edmund Haselwanter [ehaselwanter](https://github.com/ehaselwanter)
## Contributing
@@ -53,4 +117,4 @@ limitations under the License.
[1]: https://supermarket.getchef.com/cookbooks/apache-hardening
[2]: http://travis-ci.org/TelekomLabs/chef-apache-hardening
[3]: https://coveralls.io/r/TelekomLabs/chef-apache-hardening
[4]: https://gemnasium.com/TelekomLabs/chef-apache-hardening
[4]: https://gemnasium.com/TelekomLabs/chef-apache-hardening

0 comments on commit d0b8a2a

Please sign in to comment.