diff --git a/.github/workflows/contributors.yml b/.github/workflows/contributors.yml new file mode 100644 index 0000000..fb5b072 --- /dev/null +++ b/.github/workflows/contributors.yml @@ -0,0 +1,78 @@ +name: Update Contributors Information + +on: + workflow_dispatch: {} + schedule: + # Weekly on Saturdays. + - cron: "30 1 * * 6" + push: + branches: [main] + +jobs: + update-contributors: + runs-on: ubuntu-latest + permissions: + contents: write + pull-requests: write + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Update contributor list + id: contrib_list + uses: akhilmhdh/contributors-readme-action@v2.3.10 + env: + + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + with: + readme_path: COMMUNITY.md + use_username: false + commit_message: "update contributors information" + + - name: Get contributors count + id: get_contributors + env: + + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + + run: | + OWNER=$(echo $GITHUB_REPOSITORY | cut -d'/' -f1) + REPO=$(echo $GITHUB_REPOSITORY | cut -d'/' -f2) + QUERY='query { repository(owner: \"'"$OWNER"'\", name: \"'"$REPO"'\") { collaborators { totalCount } } }' + + CONTRIBUTORS=$(gh api \ + -H "Accept: application/vnd.github+json" \ + -H "X-GitHub-Api-Version: 2022-11-28" \ + "/repos/$OWNER/$REPO/contributors?per_page=100" | \ + jq '[.[] | select(.type != "Bot" and (.login | test("\\[bot\\]$") | not) and (.login | test("-bot$") | not))] | length') + + echo "Total contributors: $CONTRIBUTORS" + echo "contributors=$CONTRIBUTORS" >> $GITHUB_OUTPUT + + + - name: Update COMMUNITY.md + run: | + + CONTRIBUTORS="${{ steps.get_contributors.outputs.contributors }}" + + + perl -i -pe 's/().*?()/$1 '"$CONTRIBUTORS"' $2/' COMMUNITY.md + + git config user.name 'github-actions[bot]' + git config user.email 'github-actions[bot]@users.noreply.github.com' + git add COMMUNITY.md + git commit -m "update contributors count to $CONTRIBUTORS" || exit 0 + + - name: Push protected + uses: CasperWA/push-protected@v2 + with: + + token: ${{ secrets.PUSH_TO_PROTECTED_BRANCH }} + + + branch: main \ No newline at end of file diff --git a/.github/workflows/gitleaks.yml b/.github/workflows/gitleaks.yml new file mode 100644 index 0000000..94ae3f0 --- /dev/null +++ b/.github/workflows/gitleaks.yml @@ -0,0 +1,15 @@ +name: Check for Secrets +on: + pull_request: + push: + +jobs: + scan-for-secrets: + name: Run gitleaks + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + with: {fetch-depth: 0} + + - name: Check for GitLeaks + uses: gacts/gitleaks@v1 \ No newline at end of file diff --git a/.gitleaks.toml b/.gitleaks.toml new file mode 100644 index 0000000..fed6481 --- /dev/null +++ b/.gitleaks.toml @@ -0,0 +1,15 @@ +title = "BB2-Sample-Python-Application Gitleaks Config" + +[extend] +# useDefault will extend the base configuration with the default gitleaks config: +# https://github.com/zricethezav/gitleaks/blob/master/config/gitleaks.toml +useDefault = true + +[allowlist] +# Recommended practice is to add your secrets to a regexes array, +# not to a commits array. +regexTarget = "match" +description = "whitelist public and test secrets" +regexes = [ + '''abcdefghijklmnoppleasechange''', +] \ No newline at end of file diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..f0a6d49 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,17 @@ +# Contributor Code of Conduct + +As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities. + +We are committed to making participation in this project a harassment-free experience for everyone, regardless of the level of experience, gender, gender identity, expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, or religion. + +Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct. + +Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned with this Code of Conduct. + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers at opensource@cms.hhs.gov. + +This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.0.0, available at [http://contributor-covenant.org/version/1/0/0/](http://contributor-covenant.org/version/1/0/0/) + +## Acknowledgements + +This CODE_OF_CONDUCT.md was originally forked from the [United States Digital Service](https://usds.gov) [Justice40](https://thejustice40.com) open source [repository](https://github.com/usds/justice40-tool), and we would like to acknowledge and thank the community for their contributions. \ No newline at end of file diff --git a/COMMUNITY.md b/COMMUNITY.md new file mode 100644 index 0000000..8651d11 --- /dev/null +++ b/COMMUNITY.md @@ -0,0 +1,90 @@ +# COMMUNITY.md + +bluebutton-sample-client-python-react is supported by a dedicated team of individuals fulfilling various roles to ensure its success, security, and alignment with government standards and agency goals. + +## Project Members + +| Role | Name | Affiliation | +| :----- | :------ | :------------- | +| Maintainer | Jimmy Fagan | Nava PBC | +| Maintainer | Shivam Tiwari | ICF | +| Maintainer | Brandon Wang | ICF | +| Maintainer | Connor Lewellyn | Nava PBC | + +See [CODEOWNERS.md](.github/CODEOWNERS.md) for a list of those responsible for the code and documentation in this repository. + +See [Community Guidelines](#bluebutton-sample-client-python-react-open-source-community-guidelines) on principles and guidelines for participating in this open source project. + +## Roles & Responsibilities + +The members of bluebutton-sample-client-python-react community are responsible for guiding its development, ensuring quality standards, and fostering a collaborative environment. They play a vital role in making decisions about code contributions, handling releases, and ensuring the project meets its goals and objectives. Below is a list of the key members and their specific roles and responsibilities. We are eagerly seeking individuals who are interested in joining the community and helping shape and support these roles. + +### Maintainers: + +- @jimmyfagan +- @clewellyn-nava +- @bwang-icf +- @stiwarisemanticbits + +### Approvers: + +### Reviewers: + +| Roles | Responsibilities | Requirements | Defined by | +| ---------- | :--------------------------------------------- | :-------------------------------------------------------------------------------- | :-------------------------------------------------------- | +| member | active contributor in the community | multiple contributions to the project. | PROJECT GitHub org Committer Team | +| reviewer | review contributions from other members | history of review and authorship in a sub-project | COMMUNITY file reviewer entry, and GitHub Org Triage Team | +| approver | approve accepting contributions | highly experienced and active reviewer + contributor to a sub-project | COMMUNITY file approver entry and GitHub Triage Team | +| maintainer | set direction and priorities for a sub-project | demonstrated responsibility and excellent technical judgement for the sub-project | COMMUNITY file owner entry and GitHub Org Admin Team | + +## Contributors + + + +Total number of contributors: + + + + + +### Alumni + +We'd like to acknowledge the following individuals for their past contributions of this project: + + +## bluebutton-sample-client-python-react Open Source Community Guidelines + +This document contains principles and guidelines for participating in the bluebutton-sample-client-python-react open source community. + +### Principles + +These principles guide our data, product, and process decisions, architecture, and approach. + +- Open means transparent and participatory. +- We take a modular and modern approach to software development. +- We build open-source software and open-source process. +- We value ease of implementation. +- Fostering community includes building capacity and making our software and processes accessible to participants with diverse backgrounds and skillsets. +- Data (and data science) is as important as software and process. We build open data sets where possible. +- We strive for transparency for algorithms and places we might be introducing bias. + +### Community Guidelines + +All community members are expected to adhere to our [Code of Conduct](CODE_OF_CONDUCT.md). + +Information on contributing to this repository is available in our [Contributing file](CONTRIBUTING.md). + +When participating in bluebutton-sample-client-python-react open source community conversations and spaces, we ask individuals to follow the following guidelines: + +- When joining a conversation for the first time, please introduce yourself by providing a brief intro that includes: + - your related organization (if applicable) + - your pronouns + - your superpower, and how you hope to use it for bluebutton-sample-client-python-react +- Embrace a culture of learning, and educate each other. We are all entering this conversation from different starting points and with different backgrounds. There are no dumb questions. +- Take space and give space. We strive to create an equitable environment in which all are welcome and able to participate. We hope individuals feel comfortable voicing their opinions and providing contributions and will do our best to recognize and make space for individuals who may be struggling to find space here. Likewise, we expect individuals to recognize when they are taking up significant space and take a step back to allow room for others. +- Be respectful. +- Default to positive. Assume others' contributions are legitimate and valuable and that they are made with good intention. + +### Acknowledgements + +The Community Guidelines sections were originally forked from the [United States Digital Service](https://usds.gov) [Justice40](https://thejustice40.com) open source [repository](https://github.com/usds/justice40-tool), and we would like to acknowledge and thank the community for their contributions. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..a9cd9c2 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,106 @@ +# How to Contribute + + + +We're so thankful you're considering contributing to an [open source project of +the U.S. government](https://code.gov/)! If you're unsure about anything, just +ask -- or submit the issue or pull request anyway. The worst that can happen is +you'll be politely asked to change something. We appreciate all friendly +contributions. + +We encourage you to read this project's CONTRIBUTING policy (you are here), its +[LICENSE](LICENSE.md), and its [README](README.md). + +### Workflow and Branching + +We follow standard GitHub Flow practices: + +1. **Fork the project** (external contributors) or create a branch (internal contributors) +2. **Check out the `main` branch** +3. **Create a feature branch** with a descriptive name +4. **Write code and tests** for your change +5. **From your branch, make a pull request** against `CMSgov/bluebutton-sample-client-python-react/main` +6. **Work with repo maintainers** to get your change reviewed +7. **Wait for your change to be merged** into `main` +8. **Delete your feature branch** after successful merge + +### Coding Style and Linters + +**Style Guidelines:** +- Write clear, self-documenting code with appropriate comments + +**Linting:** +- Each application has its own linting guidelines + +### Writing Issues + +When creating an issue, please use this format: + +``` +module-name: One line summary of the issue (less than 72 characters) + +### Expected behavior + +As concisely as possible, describe the expected behavior. + +### Actual behavior + +As concisely as possible, describe the observed behavior. + +### Steps to reproduce the behavior + +1. List all relevant steps to reproduce the observed behavior +2. Include specific API calls, user actions, or configuration +3. Mention any relevant environment details + +### Additional context + +- Node version +- Operating system +- Any relevant logs or error messages +``` + +### Writing Pull Requests + +**Pull Request Guidelines:** +- File pull requests against the `main` branch +- Include a clear description of changes +- Reference any related issues +- Ensure all tests pass +- Include screenshots for UI changes + +## Documentation + +We welcome improvements to the project documentation. This includes: + +- API documentation updates +- Setup and configuration guides +- Developer tutorials +- Code comments and inline documentation + +Please file an [issue](https://github.com/CMSGov/cms-bb2-python-sdk/issues) for documentation improvements or submit a pull request with your changes. + +**Documentation Resources:** +- Developer documentation: https://cmsgov.github.io/bluebutton-developer-help/ +- Current deployment: https://sandbox.bluebutton.cms.gov +- Community discussions: https://groups.google.com/forum/#!forum/developer-group-for-cms-blue-button-api + +## Policies + +### Open Source Policy + +We adhere to the [CMS Open Source +Policy](https://github.com/CMSGov/cms-open-source-policy). If you have any +questions, just [shoot us an email](mailto:opensource@cms.hhs.gov). + +### Security and Responsible Disclosure Policy + +_Submit a vulnerability:_ Vulnerability reports can be submitted through [Bugcrowd](https://bugcrowd.com/cms-vdp). Reports may be submitted anonymously. If you share contact information, we will acknowledge receipt of your report within 3 business days. + +For more information about our Security, Vulnerability, and Responsible Disclosure Policies, see [SECURITY.md](SECURITY.md). + +## Public domain + +This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the [CC0 1.0 Universal public domain dedication](https://creativecommons.org/publicdomain/zero/1.0/). + +All contributions to this project will be released under the CC0 dedication. By submitting a pull request or issue, you are agreeing to comply with this waiver of copyright interest. \ No newline at end of file diff --git a/GOVERNANCE.md b/GOVERNANCE.md new file mode 100644 index 0000000..1eab628 --- /dev/null +++ b/GOVERNANCE.md @@ -0,0 +1,3 @@ +# Governance + +This project is governed by our [Community Guidelines](COMMUNITY.md) and [Code of Conduct](CODE_OF_CONDUCT.md). diff --git a/README.md b/README.md index 4867c78..78af969 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,35 @@ -Create a Blue Button Sandbox Account ---------------- +BlueButton Sample Python Client Application +===================================================== + +## Project Description +A sample application, written in Python with Flask and the Python SDK + +## About the Project +The [Blue Button 2.0 API](https://bluebutton.cms.gov/) provides Medicare enrollee claims data to applications using the [OAuth2.0 authorization flow](https://datatracker.ietf.org/doc/html/rfc6749). We aim to provide a developer-friendly, standards-based API that enables people with Medicare to connect their claims data to the applications, services, and research programs they trust. + +## Core Team +A list of core team members responsible for the code and documentation in this repository can be found in [COMMUNITY.md](COMMUNITY.md). + +## Development and Software Delivery Lifecycle +The following guide is for members of the project team who have access to the repository as well as code contributors. The main difference between internal and external contributions is that external contributors will need to fork the project and will not be able to merge their own pull requests. For more information on contributing, see: [CONTRIBUTING.md](./CONTRIBUTING.md). + +# Local Development + +## Repository Structure +``` +├── client +│ ├── public +│ ├── src +├── server +├── selenium_tests +``` + +## Setup + +### Create a Blue Button Sandbox Account Create an account at the link below, and register your test application, to get your Blue Button Sandbox Credentials which will allow you to access the Blue Button synthetic data. These credentials will be necessary to run this sample application as well as -utilize the Blue Button data within your own applcation. See the section below 'Running the Back-end & Front-end'. +utilize the Blue Button data within your own applcation. https://sandbox.bluebutton.cms.gov/v1/accounts/create @@ -14,15 +41,12 @@ http://localhost:3001/api/bluebutton/callback/ When you are ready to run your own application, you can change this value to the url that you need. Just log into your Blue Button Sandbox account and select 'View/Edit App->'. -Setup Docker & Python ---------------- +## Installation Install and setup Docker. Go to https://docs.docker.com/get-started/ and follow the directions. Install Python: https://www.python.org/downloads/ -Running the Back-end & Front-end ---------------- - +## Running Once Docker and Python are Installed then do the following: ``` @@ -52,28 +76,23 @@ http://localhost:3000 To see the process of authenticating with Blue Button via Medicare.gov and retrieve EoB data just click on the 'Authorize' button. -BB2 Sandbox User ------------ -To ensure data displays properly in the sample application please use a -Blue Button Sandbox user that has PDE (Part-D Events) EoBs (Explanation of Benefits). An example of a user with this -data would be: BBUser10000 (PWD: PW10000!) or BBUser09999 (PWD: PW09999!) - -Development ------------ +## Developing Read the comments in the code to understand the application and where you will need to make adjustments/changes as well as some suggestions for best practices. -Python SDK ----------- +### BB2 Sandbox User +To ensure data displays properly in the sample application please use a +Blue Button Sandbox user that has PDE (Part-D Events) EoBs (Explanation of Benefits). An example of a user with this +data would be: BBUser10000 (PWD: PW10000!) or BBUser09999 (PWD: PW09999!) + +### Python SDK The sample app utilizes our [Python SDK](https://github.com/CMSgov/cms-bb2-python-sdk). Please review our SDK documentation for more information and additional features available for your use. - -Debugging server component --------------------------- +## Debugging debugpy remote debugging enabled on port 10678 for server in docker compose, developer can attach to server from IDE e.g. vscode. To set up the run config to debug in vscode, add below contents to `.vscode/launch.json` @@ -104,6 +123,56 @@ To set up the run config to debug in vscode, add below contents to `.vscode/laun } ``` -Error Responses and handling: ------------------------------ -[See ErrorResponses.md](./ErrorResponses.md) \ No newline at end of file +### Error Responses and handling: +[See ErrorResponses.md](./ErrorResponses.md) + +# Contributing +Thank you for considering contributing to an Open Source project of the US Government! For more information about our contribution guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md). + +## Branching Model +This project follows standard GitHub flow practices: + +* Make changes in feature branches and merge to `main` frequently +* Pull-requests are reviewed before merging +* Tests should be written for changes introduced +* Each change should be deployable to production + +# Community +The Blue Button Web Server team is taking a community-first and open source approach to the product development of this tool. We believe government software should be made in the open and be built and licensed such that anyone can download the code, run it themselves without paying money to third parties or using proprietary software, and use it as they will. + +We know that we can learn from a wide variety of communities, including those who will use or will be impacted by the tool, who are experts in technology, or who have experience with similar technologies deployed in other spaces. We are dedicated to creating forums for continuous conversation and feedback to help shape the design and development of the tool. + +We also recognize capacity building as a key part of involving a diverse open source community. We are doing our best to use accessible language, provide technical and process documents, and offer support to community members with a wide variety of backgrounds and skillsets. + +# Community Guidelines +Principles and guidelines for participating in our open source community are can be found in [COMMUNITY.md](COMMUNITY.md). Please read them before joining or starting a conversation in this repo or one of the channels listed below. All community members and participants are expected to adhere to the community guidelines and code of conduct when participating in community spaces including: code repositories, communication channels and venues, and events. + +# Governance +For more information about our governance, see [GOVERNANCE.md](GOVERNANCE.md). + +# Feedback +Got questions? Need help troubleshooting? Want to propose a new feature? Contact the Blue Button 2.0 team and connect with the community in our [Google Group](https://groups.google.com/forum/#!forum/Developer-group-for-cms-blue-button-api). + +# Policies +### Open Source Policy + +We adhere to the [CMS Open Source Policy](https://github.com/CMSGov/cms-open-source-policy). If you have any questions, just [shoot us an email](mailto:opensource@cms.hhs.gov). + +### Security and Responsible Disclosure Policy + +_Submit a vulnerability:_ Vulnerability reports can be submitted through [Bugcrowd](https://bugcrowd.com/cms-vdp). Reports may be submitted anonymously. If you share contact information, we will acknowledge receipt of your report within 3 business days. + +For more information about our Security, Vulnerability, and Responsible Disclosure Policies, see [SECURITY.md](SECURITY.md). + +### Software Bill of Materials (SBOM) + +A Software Bill of Materials (SBOM) is a formal record containing the details and supply chain relationships of various components used in building software. + +In the spirit of [Executive Order 14028 - Improving the Nation's Cyber Security](https://www.gsa.gov/technology/it-contract-vehicles-and-purchasing-programs/information-technology-category/it-security/executive-order-14028), a SBOM for this repository is provided here: https://github.com/CMSGov/bluebutton-web-server/network/dependencies. + +For more information and resources about SBOMs, visit: https://www.cisa.gov/sbom. + +# Public Domain +This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the [CC0 1.0 Universal public domain dedication](https://creativecommons.org/publicdomain/zero/1.0/) as indicated in [LICENSE](LICENSE). + +All contributions to this project will be released under the CC0 dedication. By submitting a pull request or issue, you are agreeing to comply with this waiver of copyright interest. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..07342ef --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,12 @@ +# Security and Responsible Disclosure Policy + +The Centers for Medicare & Medicaid Services is committed to ensuring the security of the American public by protecting their information from unwarranted disclosure. We want security researchers to feel comfortable reporting vulnerabilities they have discovered so we can fix them and keep our users safe. We developed our disclosure policy to reflect our values and uphold our sense of responsibility to security researchers who share their expertise with us in good faith. + +*Submit a vulnerability:* Vulnerability reports can be submitted through [Bugcrowd](https://bugcrowd.com/cms-vdp). Reports may be submitted anonymously. If you share contact information, we will acknowledge receipt of your report within 3 business days. + +Review the HHS Disclosure Policy and websites in scope: +[https://www.hhs.gov/vulnerability-disclosure-policy/index.html](https://www.hhs.gov/vulnerability-disclosure-policy/index.html). + +This policy describes *what systems and types of research* are covered under this +policy, *how to send* us vulnerability reports, and *how long* we ask security +researchers to wait before publicly disclosing vulnerabilities. \ No newline at end of file diff --git a/code.json b/code.json new file mode 100644 index 0000000..d83fa90 --- /dev/null +++ b/code.json @@ -0,0 +1,50 @@ +{ + "name": "bluebutton-sample-client-python-react", + "description": "A sample application connecting to BlueButton using the Python SDK.", + "status": "Production", + "permissions": { + "licenses": [ + { + "name": "CC0-1.0", + "URL": "https://github.com/CMSgov/bluebutton-sample-client-python-react/blob/main/LICENSE" + } + ], + "usageType": [ + "openSource" + ] + }, + "organization": "Centers for Medicare & Medicaid Services", + "repositoryURL": "https://github.com/CMSgov/bluebutton-sample-client-python-react", + "repositoryVisibility": "public", + "vcs": "git", + "laborHours": 12636, + "reuseFrequency": { + "forks": 1 + }, + "languages": [ + "python", + "javascript" + ], + "maintenance": "internal", + "contractNumber": [ + "0" + ], + "date": { + "created": "2021-09-27T18:47:01Z", + "lastModified": "2025-08-12T14:09:41Z", + "metaDataLastUpdated": "2025-09-09T15:03:06.962Z" + }, + "tags": [ + "sdk", + "bluebutton", + "sample-app", + "python", + "flask" + ], + "contact": { + "email": "jimmyfagan@navapbc.com", + "name": "Jimmy Fagan" + }, + "feedbackMechanism": "https://github.com/CMSgov/bluebutton-sample-client-python-react/issues", + "AIUseCaseID": "0" +} \ No newline at end of file