From 2ebfdd04b63309e105d4177a59bf5bdd61ae839f Mon Sep 17 00:00:00 2001 From: Steve McGrath Date: Tue, 31 Dec 2024 14:11:58 -0600 Subject: [PATCH] Updated README and relevent github templates --- .github/CONTRIBUTING.md | 91 +++++++++++++++++++++++ .github/ISSUE_TEMPLATE/bug_report.md | 31 ++++++++ .github/ISSUE_TEMPLATE/feature_request.md | 17 +++++ .github/PULL_REQUEST_TEMPLATE.md | 34 +++++++++ .github/SECURITY.md | 35 +++++++++ .gitignore | 3 +- README.md | 53 ++++++++++++- 7 files changed, 262 insertions(+), 2 deletions(-) create mode 100644 .github/CONTRIBUTING.md create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 .github/SECURITY.md diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..b36f5c8 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,91 @@ +# Contributing + +I'm really glad you're reading this, because we need volunteer developers to help this project come to fruition. + +Here are some important resources: + +- [Our Documentation](https://pytenable.rtfd.io) is a good resource as to what is currently considered stable. +- [Our roadmap](https://github.com/tenable/tenable-connectors/milestones) is a 10k ft. view of where we're headed. +- [The Tenable Community Integrations Section](https://community.tenable.com/s/topic/0TOf2000000HPDKGA4) is a great + place to discuss working with the Tenable APIs in general. +- Bugs? [Github Issues](https://github.com/tenable/tenable-connectors/issues) is where to report them +- [SECURITY.md](./SECURITY.md) outlines our process for reviewing security bugs that are reported. + +## Steps to contribute + +1. If one doesn't already exist, [create an issue](https://github.com/tenable/tenable-connectors/issues/new) for the + bug or feature you intend to work on. +2. Create your own fork, and check it out. +3. Write your code locally. It is preferred if you create a branch for each issue or feature you work on, though not required. +4. Please add a test for any bug fix or feature being added. (Not required, but we will love you if you do) +5. Run all test cases and add any additional test cases for code you've contributed. +6. Lint your code by running PyLint. +7. Once all tests have passed, commit your changes to your fork and then create a Pull Request for review. Please make + sure to fill out the PR template when submitting. + +### Pull Requests and Code Contributions + +- All tests must pass before any PR will be merged. +- Please follow [Coding Conventions](#coding-conventions) for styling guidelines +- Always write a clear log message for your commits. One-line messages are fine for small changes, but bigger changes + should look like this: + +``` +$ git commit -m "A brief summary of the commit +> +> A paragraph describing what changed and its impact." +``` + +### Branches + +The `main` branch is used for the current deployed releases. + +## Testing + +We use py.test extensively to test inputs, outputs, and failure conditions. Further we use tooling mock interactions +with the APIs using `responses` when we would be making a successful call so that there is a consistency to whats being +tested against. + +### Security Testing + +We have implemented a few required security checks before allowing a merge to main. + +#### Source Code Scanning + +Static Code Analysis is implemented to scan the codebase for any vulnerabilities that may exist. The code base is +scanned daily at a minimum to monitor for new vulnerabilities. + +#### Software Composition Analysis + +Software Composition Analysis is performed to monitor third party dependencies for vulnerabilities that may exist in +direct or transitive dependencies. + +#### Secret Scanning + +Each commit is scanned for the presence of any value that may contain a secret. If a commit contains a secret, it will +be blocked from being merged. + +## Coding conventions + +Start reading our code and you'll get the hang of it. We optimize for readability: + +- We indent using four spaces (soft tabs) +- We use Google Doc-strings format +- We conform to PEP8 as much as possible, only breaking convention when necessary. +- We ALWAYS put spaces after list items and method parameters (`[1, 2, 3]`, not `[1,2,3]`), around operators + (`x += 1`, not `x+=1`). +- This is open source software. Consider the people who will read your code, and make it look nice for them. It's + sort of like driving a car: Perhaps you love doing donuts when you're alone, but with passengers the goal is to + make the ride as smooth as possible. + - Code Readability is paramount. If something is difficult to follow, we generally expect the code to be broken + down into readable & manageable components. + - Code should be commented not only to describe what it is, but should also help to tell the story of what we are + trying to accomplish and why. + - We generally prefer to conform to DRY as often as possible, however will break DRY for purpose of readability. +- We prefer that all classes are in camelCase. +- We generally want all function names and variables to be in snake_case. There are notable exceptions to this + when it's simply unavoidable. +- The documentation is directly generated from the source code, this means that well-formed doc-strings are critical. + +Thanks, +Steven McGrath, Tenable, Inc. diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..ad70f39 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,31 @@ +--- +name: Bug report +about: Create a report to help us improve +--- + +**Describe the bug** +A clear and concise description of what the bug is. + +**To Reproduce** +Steps to reproduce the behavior: + +1. Go to '...' +2. Call '....' +3. Do '....' +4. See error + +**Expected behavior** +A clear and concise description of what you expected to happen. + +**Screenshots** +If applicable, add screenshots to help explain your problem. + +**System Information (please complete the following information):** + +- OS: [e.g. MacOS] +- Architecture [e.g. AMD64, ARM64] +- Impacted Connector [e.g. qualys2tone] +- Memory [e.g. 4G] + +**Additional context** +Add any other context about the problem here. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..066b2d9 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,17 @@ +--- +name: Feature request +about: Suggest an idea for this project + +--- + +**Is your feature request related to a problem? Please describe.** +A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] + +**Describe the solution you'd like** +A clear and concise description of what you want to happen. + +**Describe alternatives you've considered** +A clear and concise description of any alternative solutions or features you've considered. + +**Additional context** +Add any other context or screenshots about the feature request here. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..e8b9308 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,34 @@ +# Description + +Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context. +List any dependencies that are required for this change. + +Fixes # (issue) + +## Type of change + +Please delete options that are not relevant. + +- [ ] Bug fix (non-breaking change which fixes an issue) +- [ ] New feature (non-breaking change which adds functionality) +- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) +- [ ] This change requires a documentation update + +# How Has This Been Tested? + +Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. Please also +list any relevant details for your test configuration + +- [ ] Test A +- [ ] Test B + +# Checklist: + +- [ ] My code follows the style guidelines of this project +- [ ] I have performed a self-review of my own code +- [ ] I have commented my code, particularly in hard-to-understand areas +- [ ] I have made corresponding changes to the documentation +- [ ] My changes generate no new warnings +- [ ] I have added tests that prove my fix is effective or that my feature works +- [ ] New and existing unit tests pass locally with my changes +- [ ] Any dependent changes have been merged and published in downstream modules diff --git a/.github/SECURITY.md b/.github/SECURITY.md new file mode 100644 index 0000000..51543cc --- /dev/null +++ b/.github/SECURITY.md @@ -0,0 +1,35 @@ +# Security Policies and Procedures + +This document outlines security procedures and general policies for the `pyTenable` +project. + +- [Contributing](./CONTRIBUTING.md) + +## Reporting an Issue + +The `tenable-connectors` team and community take all security issues in `tenable-connectors` seriously. Thank you for +improving the security of `tenable-connectors`. We appreciate your efforts and responsible disclosure and will make +every effort to acknowledge your contributions. + +Report security bugs by emailing the team at vulnreport@tenable.com. + +The team will acknowledge your email within 48 hours, and will send a more detailed response within 48 hours after +acknowledgement indicating the next steps in handling your report. After the initial reply to your report, the security +team will keep you informed of the progress towards a fix and full announcement, and may ask for additional information +or guidance. + +Report security bugs in third-party modules to the person or team maintaining the module. + +## Disclosure Policy + +When the security team receives a security bug report, they will assign it to a primary handler. This person will +coordinate the fix and release process, involving the following steps: + +- Confirm the problem and determine the affected versions. +- Audit code to find any potential similar problems. +- Prepare fixes for all releases still under maintenance. These fixes will be + released as fast as possible to npm. + +## Comments on this Policy + +If you have suggestions on how this process could be improved please submit a pull request. diff --git a/.gitignore b/.gitignore index 418b12b..2a208d3 100644 --- a/.gitignore +++ b/.gitignore @@ -9,4 +9,5 @@ __pycache__ .vars .secrets .vars -requirements.txt \ No newline at end of file +requirements.txt +/build.sh diff --git a/README.md b/README.md index 2ff9f9a..3592d47 100644 --- a/README.md +++ b/README.md @@ -1 +1,52 @@ -# tenable-connectors \ No newline at end of file +# Tenable Connectors Mono-Repo + +This is the Tenable Integration Framework's officially supported connectors repository. All connectors that are +accepted into this main branch will be built and deployed for use with the Tenable Integration Framework (hereby simply +referred as the "framework" within this document). While each connector is effectively a individual python project +they are all collectively stored here in order to provide a consistent and unified testing and deployment process that +can be controlled and maintained in a single place. + +## Repository Layout + +The `base` folder contains the required docker-related files for universally building any of the connecters. The +`Dockerfile` that is stored within this folder should generally be quite close to the one that is vendored within the +`tenint` python library that any developer can use to build & test connectors locally. These files should rarely be +updated (mostly to update the pinnings for any dependent libraries). + +The `connectors` folder contains a list of sub-folders (one for each connector) and the folder names should closely +match the name of the connector itself. + +## Connector Layout + +Connectors are built using the template defined within the `tenint` python library and at a minimum must contain the +following files: + +- **pyproject.toml**: This file contains all the relevent information on how to setup the connector with `uv`, as well + as the required metadata in order to construct the marketplace object for the connector. For details on the required + fields, refer to the documentation in the `tenint` library. + +- **connector.py**: The connector runtime script. This file (as defined by the tenint library) describes the connector + configuration settings, any required credential settings, and the connector's `main` function to execute whatever + additional code is needed to launch the connector itself. + +- **logo.svg**: An Scalable Vector Graphics file with the associated logo icon to be displayed with the connector in + the connector marketplace. + +- **README.md**: A readme file with any details, instructions, or other information related to the connector itself. + +- **tests**: The folder containing the unit tests for the connector. These tests are run using the `pytest` testing suite. + +Most of the connectors will contain additional files and folders depending on whats required to drive the connector. +This is prerfectly alright, but all of the above must exist. Some additional requirements that all connectors must at a +minimum meet are the following: + +- **Greater than 80% test coverage** +- **Clean code linting from ruff** +- **Clean CodeQL report** +- **No issues greater than medium in Bandit** +- **No discovered issues from pip-audit** +- **No discovered issued from Snyk** + +## How to develop a connector + +**NOTE** Will be written when we're ready to start accepting outside written integrations