Welcome! We're excited you want to take part in the FalconPy community!
Please review this document for details regarding getting started with your first contribution, packages you'll need to install as a developer, and our Pull Request process. If you have any questions, please let us know by posting your question in the discussion board.
Before you begin: Have you read the Code of Conduct? The Code of Conduct helps us establish community norms and how they'll be enforced.
- See something? Say something! Submit a bug report to let the community know what you've experienced or found. Bonus points if you suggest possible fixes or what you feel may resolve the issue. For example: "Attempted to use the XZY API class but it errored out. Could a more descriptive error code be returned?"
- Join the discussion board where you can:
- Interact with other members of the community
- Suggest new functionality
- Provide feedback
- Show others how you are using FalconPy
- Submit a Pull Request
We use GitHub issues to track:
- bugs (
BUG) - documentation and linking issues (
DOC,LINK) - enhancements (
ENH) - security concerns (
SEC)
We use GitHub's discussion board functionality to handle community discussions related to:
In order for your pull request to be merged, it must pass code style and unit testing requirements. Pull requests that do not receive responses to feedback or requests for changes will be closed.
When you submit code changes, your submissions are understood to be under the same Unlicense license that covers the project. If this is a concern, contact the maintainers before contributing.
requirements-dev.txt contains Python modules required for unit test development. Review this file's contents and install missing requirements as needed or install them all with the following command.
pip3 install -r requirements-dev.txt- All submitted code must also have an associated unit test that tests all code paths within this new segment. (:100: percent coverage)
- If the code submission is already covered by an existing unit test, additional unit tests are not required.
- Please include coverage testing results in your Pull Request. (Example: PR #67)
- Unit testing is intended to prove out code formatting and functionality, not necessarily API functionality. Unit testing does not need to communicate with the API in order to provide the necessary coverage.
- We use
banditandCodeQLfor static code analysis.- Please include bandit analysis results in the section provided in your Pull Request.
- Pull Requests that produce alerts in
banditorCodeQLmay be closed without merging.
- All new contributions must pass unit testing before they will be merged.
- For scenarios where unit testing passes in the PR and fails post-merge, a maintainer will address the issue. If the problem is programmatic and related to code within the pull request, the merge may be reverted.
- The util folder contains a BASH script,
run-tests.sh, that contains the parameters used that match unit testing performed as part of our GitHub workflows.
You can run all unit tests and perform a bandit analysis by executing the command
util/run-tests.shfrom the root of the project directory.
| Test type | Result |
|---|---|
| Cross-operating system unit testing |    |
| Cross-region unit testing |    |
| Coverage |  |
| Static analysis |  |
Cross-operating system unit testing is performed in US1.
Our Pull Request template provides an area for you to post the coverage results from your local unit tests. This table is generated by the command coverage report and is executed when you use the "run-tests.sh" BASH script found in the util folder. This table is output only when all unit tests have passed successfully, and is a required element for Pull Request approval.
Name Stmts Miss Cover
---------------------------------------------------------------
src/falconpy/__init__.py 10 0 100%
src/falconpy/_endpoint.py 1 0 100%
src/falconpy/_result.py 8 0 100%
src/falconpy/_service_class.py 31 0 100%
src/falconpy/_util.py 80 0 100%
src/falconpy/_version.py 8 0 100%
src/falconpy/api_complete.py 77 0 100%
src/falconpy/cloud_connect_aws.py 66 0 100%
src/falconpy/cspm_registration.py 114 0 100%
src/falconpy/detects.py 34 0 100%
src/falconpy/device_control_policies.py 67 0 100%
src/falconpy/event_streams.py 15 0 100%
src/falconpy/falconx_sandbox.py 78 0 100%
src/falconpy/firewall_management.py 130 0 100%
src/falconpy/firewall_policies.py 68 0 100%
src/falconpy/host_group.py 61 0 100%
src/falconpy/hosts.py 37 0 100%
src/falconpy/incidents.py 39 0 100%
src/falconpy/intel.py 89 0 100%
src/falconpy/iocs.py 58 0 100%
src/falconpy/oauth2.py 30 0 100%
src/falconpy/prevention_policy.py 67 0 100%
src/falconpy/real_time_response.py 135 0 100%
src/falconpy/real_time_response_admin.py 82 0 100%
src/falconpy/sensor_update_policy.py 103 0 100%
src/falconpy/spotlight_vulnerabilities.py 15 0 100%
src/falconpy/user_management.py 75 0 100%
---------------------------------------------------------------
TOTAL 1578 0 100%Our Pull Request template provides an area for you to post the bandit analysis results from your local unit tests. This detail is generated by the command bandit ... and is executed when you run the "run-tests.sh" BASH script found in the util folder. These results are produced only when all unit tests have passed successfully, and are required for Pull Request approval.
[main] INFO profile include tests: None
[main] INFO profile exclude tests: None
[main] INFO cli include tests: None
[main] INFO cli exclude tests: None
[main] INFO running on Python 3.9.2
Run started:2021-03-26 21:13:00.083912
Test results:
No issues identified.
Code scanned:
Total lines of code: 6415
Total lines skipped (#nosec): 0
Run metrics:
Total issues (by severity):
Undefined: 0.0
Low: 0.0
Medium: 0.0
High: 0.0
Total issues (by confidence):
Undefined: 0.0
Low: 0.0
Medium: 0.0
High: 0.0
Files skipped (0):For more information regarding PyTest, and how we leverage it to perform unit testing, refer to the PyTest documentation.
To find out more above Coverage, review their website.
To read more about bandit, you can visit their documentation website.
All submitted code must meet minimum linting requirements. We use the Flake8 framework for our lint specification.
- All code that is included within the installation package must pass linting workflows when the Pull Request checks have completed.
- We use
flake8,CodeQL,pydocstyleandpylintto power our linting workflows. - You will be asked to correct linting errors before your Pull Request will be approved.
- We use
- Unit tests do not need to meet this requirement, but try to keep linting errors to a minimum.
- Samples are checked for linting, but failures will not stop builds at this time.
- Refer to the
lint.shscript within the util folder to review our standard linting parameters.
You can quickly check the linting for all code within the src folder by executing the command
util/lint.shfrom the root of the project directory.
More information about Flake8 can be found here.
More information about pydocstyle can be found here.
More information about Pylint can be found here.
In an effort to maintain backwards compatibility, we thoroughly unit test every Pull Request for all versions of Python we support. These unit tests are intended to catch general programmatic errors, possible vulnerabilities (via bandit and CodeQL) and potential breaking changes.
If you have to adjust a unit test locally in order to produce passing results, there is a possibility you are working with a potential breaking change.
Please fully document changes to unit tests within your Pull Request. If you did not specify "Breaking Change" on the punch list in the description, and the change is identified as possibly breaking, this may delay or prevent approval of your PR.
Please do not target the main branch with your Pull Request unless it is the only branch or you are directed to do so by a maintainer.
If you are submitting a sample for inclusion in our samples library your submission should target the samples branch.
All other pull requests should target the dev branch.
Depending on the nature of your pull request, you may be contacted by a maintainer and asked to target a new branch specific to your submission.
Please use the pull request template provided, making sure the following details are included in your request:
- Is this a breaking change?
- Are all new or changed code paths covered by unit testing?
- A complete listing of issues addressed or closed with this change.
- A complete listing of any enhancements provided by this change.
- Any usage details developers may need to make use of this new functionality.
- Does additional documentation need to be developed beyond what is listed in your Pull Request?
- Any other salient points of interest.
Please review this list and confirm none of the following concerns exist within your request. Pull requests containing any of these elements will be prevented from merging to the code base and may be closed.
| Concern | Restriction |
|---|---|
| Archives | Limited exceptions to be reviewed by maintainers on a case by case basis. Absolutely unacceptable within the src folder. |
| Binaries | Compiled binaries, regardless of intent should not be included in the code base or in samples. |
| Disparaging references to 3rd party vendors in source or content | We are here to collaborate regarding FalconPy, not bash the work of others. |
| Inappropriate language, comments or references found within source or content | Comments (and comment art) must not detract from code legibility or impact overall package size. All content published to this repository (source or otherwise) must follow the Code of Conduct. |
| Intellectual property that is not yours | Copywrited works, trademarks, source code or image assets belonging to others should not be posted to this repository whatsoever. CrowdStrike assets which are already released into the Public Domain will be accepted as long as their usage meets other restrictions, the rules specified in the Code of Conduct, and the guidelines set forth in the CrowdStrike Brand Guide. |
| Relative links in README files | This impacts our package deployment as these files are consumed as part of the build process. All link and image references within README files must contain the full URL. |
All Pull Requests must be approved by at least one maintainer. Once approved, a maintainer will perform the merge and execute any backend processes related to package deployment.
At this point in time, main, dev and samples are protected branches.
To read more about the FalconPy code review and packaging cycle, please review the contents of this page.
Stable versions of crowdstrike-falconpy and crowdstrike-falconpy-dev are released by maintainers on a regular cadence based upon current activity and the results of testing.
For more detail, review the package release cycle documentation.
If you have suggestions on how this process could be improved, please let us know by starting a new discussion.
