From 0ba894a2ad9f64f1f00ab3a462df2ce014335d9a Mon Sep 17 00:00:00 2001 From: Stefan Wild Date: Tue, 22 Sep 2026 14:54:10 -0700 Subject: [PATCH 1/4] Updated support line and put in a default security contact. --- README.md | 2 +- SECURITY.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 18a370e..b165ac4 100644 --- a/README.md +++ b/README.md @@ -109,7 +109,7 @@ We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for gu ## Support -This project acknowledges support from the U.S. Department of Energy's Genesis Mission. +This project acknowledges support from the U.S. Department of Energy (DOE), Office of Science, Office of Advanced Scientific Computing Research in alignment with DOE's Genesis Mission. ## License diff --git a/SECURITY.md b/SECURITY.md index ee28f21..ba944ec 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -4,7 +4,7 @@ **Please do not report security vulnerabilities through public GitHub issues.** -Instead, please email your findings to [security contact email to be determined]. +Instead, please email your findings to modcon-base-code@lbl.gov. Please include the following details in your report: - Description of the vulnerability From 9f47840392a020ea5633a0538d7005e986ebd33e Mon Sep 17 00:00:00 2001 From: Stefan Wild Date: Thu, 5 Nov 2026 15:41:33 -0800 Subject: [PATCH 2/4] Proposing some modest updates based on recent experience. --- .github/ISSUE_TEMPLATE/bug_report.md | 9 +++- .github/pull_request_template.md | 20 ++++++-- .github/workflows/ci.yml | 71 +++++++++++++++++++++------ .github/workflows/publish.yml | 49 ++++++++++++++----- .gitignore | 6 +++ CHANGELOG.md | 13 +++++ CONTRIBUTING.md | 20 ++++++-- README.md | 73 ++++++++++++++++++++++------ SECURITY.md | 70 +++++++++++++++++++++++++- docs/faq.md | 1 - docs/getting_started.md | 55 +++++++++++++++++++++ docs/index.md | 4 +- 12 files changed, 337 insertions(+), 54 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 3f97083..fe4e323 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -7,6 +7,10 @@ assignees: '' --- +For suspected vulnerabilities or exposed credentials, follow SECURITY.md instead of +opening a public issue. Sanitize logs, screenshots, notebooks, and traces; do not +include secrets, restricted data, or private operational details. + ## Describe the Bug A clear and concise description of what the bug is. @@ -35,8 +39,9 @@ If applicable, add screenshots to help explain your problem. Please complete the following information: - OS: [e.g. Linux, Windows, macOS] -- Python Version: [e.g. 3.9, 3.10] -- Project Version: [e.g. 1.0.0] +- Runtime/tool versions (if applicable): +- Project version or commit: +- Hardware, scheduler, container image, or agent client (if applicable): ## Additional Context diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index a164d95..b78090f 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -20,15 +20,29 @@ Please describe the tests that you ran to verify your changes. Provide instructi - [ ] Test A - [ ] Test B +## AI Assistance + +> AI tools used: [Name the tools used to develop this PR, or write "None".] +> +> Scope of assistance: [Describe what they helped produce or review.] +> +> Human validation: [Describe how the author checked the AI-assisted work; human PR review is still required.] + ## Checklist +The sensitive-information reminder below is optional scaffolding for adopting +repositories; the artifact review matters, not copying this checklist or policy text. + +- [ ] I have removed secrets, local account names, identifying paths, and unnecessary personal identifiers from examples, logs, notebooks, and attachments, following [SECURITY.md](../SECURITY.md#credentials-and-sensitive-outputs); suspected vulnerabilities are reported privately - [ ] 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 explained non-obvious behavior where needed - [ ] 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 passed locally with my changes +- [ ] I have added appropriate validation (tests, schema/skill checks, or documentation checks), or explained non-applicability +- [ ] Applicable checks passed; I have stated untested platforms and any external calls or resource costs +- [ ] I have completed the AI Assistance section above, including "None" if applicable, and arranged human review +- [ ] Changes to workflows, tool authority, credentials, or deployment boundaries have been called out for review, if applicable - [ ] Any dependent changes have been merged and published in downstream modules ## Screenshots (if applicable) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b27bf24..ccbb7de 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -5,20 +5,56 @@ on: branches: [ main, develop ] pull_request: branches: [ main, develop ] + workflow_dispatch: + inputs: + check_external_urls: + description: Check external documentation URLs (advisory only) + type: boolean + default: false + +permissions: + contents: read jobs: + documentation: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + with: + persist-credentials: false + + - name: Check spelling + uses: crate-ci/typos@4c8b7f51ca60df14e3c5ca82770dfbbe6c3dae85 # v1.52.0 + with: + files: '*.md docs/' + + - name: Check local documentation links + uses: lycheeverse/lychee-action@e7477775783ea5526144ba13e8db5eec57747ce8 # v2 + with: + args: --offline --include-fragments=anchor-only --no-progress '*.md' 'docs/**/*.md' + + - name: Check external documentation URLs + if: github.event_name == 'workflow_dispatch' && inputs.check_external_urls + continue-on-error: true + uses: lycheeverse/lychee-action@e7477775783ea5526144ba13e8db5eec57747ce8 # v2 + with: + fail: false + args: --exclude-all-private --timeout 20 --max-retries 2 --no-progress '*.md' 'docs/**/*.md' + check-lock: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + with: + persist-credentials: false - name: Set up Python - uses: actions/setup-python@v5 + uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5 with: python-version: '3.11' - name: Install uv - uses: astral-sh/setup-uv@v3 + uses: astral-sh/setup-uv@8d55fbecc275b1c35dbe060458839f8d30439ccf # v3 - name: Check uv.lock is up-to-date run: uv lock --check @@ -26,26 +62,28 @@ jobs: lint: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + with: + persist-credentials: false - name: Set up Python - uses: actions/setup-python@v5 + uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5 with: python-version: '3.11' - name: Install uv - uses: astral-sh/setup-uv@v3 + uses: astral-sh/setup-uv@8d55fbecc275b1c35dbe060458839f8d30439ccf # v3 with: enable-cache: true - name: Sync dependencies - run: uv sync --group dev + run: uv sync --locked --group dev - name: Lint with ruff - run: uv run ruff check . + run: uv run --locked ruff check . - name: Format check with ruff - run: uv run ruff format . --check + run: uv run --locked ruff format . --check test: runs-on: ubuntu-latest @@ -54,26 +92,29 @@ jobs: python-version: ['3.11', '3.12', '3.13', '3.14'] steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + with: + persist-credentials: false - name: Set up Python ${{ matrix.python-version }} - uses: actions/setup-python@v5 + uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5 with: python-version: ${{ matrix.python-version }} - name: Install uv - uses: astral-sh/setup-uv@v3 + uses: astral-sh/setup-uv@8d55fbecc275b1c35dbe060458839f8d30439ccf # v3 with: enable-cache: true - name: Sync dependencies - run: uv sync --group test + run: uv sync --locked --group test - name: Run tests with pytest - run: uv run pytest --cov=basetemplate --cov-report=xml + run: uv run --locked pytest --cov=basetemplate --cov-report=xml - name: Upload coverage to Codecov - uses: codecov/codecov-action@v4 + if: vars.ENABLE_CODECOV == 'true' + uses: codecov/codecov-action@b9fd7d16f6d7d1b5d2bec1a2887e65ceed900238 # v4 with: file: ./coverage.xml flags: unittests diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 893f0e8..8bce6f6 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -1,30 +1,57 @@ name: Publish on: - # Uncomment to publish on version tags - # push: - # tags: - # - "v*" + release: + types: [published] + +permissions: + contents: read jobs: - build-publish: + build: + if: vars.ENABLE_PYPI_PUBLISH == 'true' && startsWith(github.event.release.tag_name, 'v') runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + with: + ref: ${{ github.event.release.tag_name }} + persist-credentials: false - name: Set up Python - uses: actions/setup-python@v5 + uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5 with: python-version: '3.11' - name: Install uv - uses: astral-sh/setup-uv@v3 + uses: astral-sh/setup-uv@8d55fbecc275b1c35dbe060458839f8d30439ccf # v3 + + - name: Check lock + run: uv lock --check - name: Build package run: uv build - - name: Publish to PyPI - uses: pypa/gh-action-pypi-publish@release/v1 + - name: Store distributions + uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4 + with: + name: distributions + path: dist/ + if-no-files-found: error + + publish: + needs: build + runs-on: ubuntu-latest + environment: pypi + permissions: + id-token: write + steps: + - name: Retrieve distributions + uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4 + with: + name: distributions + path: dist/ + + - name: Publish to PyPI with Trusted Publishing + uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # release/v1 with: packages-dir: dist/ - # Note: Set PYPI_API_TOKEN secret in repository settings diff --git a/.gitignore b/.gitignore index 348668b..a396370 100644 --- a/.gitignore +++ b/.gitignore @@ -97,6 +97,12 @@ celerybeat.pid # Environments .env +.env.* +!.env.example +!.env.template +!.env.*.example +!.env.*.template +.envrc.local .venv env/ venv/ diff --git a/CHANGELOG.md b/CHANGELOG.md index 7fbaa4a..f512da0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,8 +9,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added - Initial repository setup with best practices template +- Spelling and local-link checks in the existing CI workflow, plus optional, + manual-only external URL checks whose results are advisory and non-blocking. ### Changed +- Separate the shared repository baseline from Python starter defaults, with + conditional requirements for skills, specifications, services, scientific workflows, + and content. +- Document non-destructive adoption, administrator setup, and support/reproducibility limits. +- Clarify that sensitive-information checks assess public artifacts, not the presence + of duplicated sanitization policies; repository-specific reminders are optional. ### Deprecated @@ -19,6 +27,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Fixed ### Security +- Harden CI with immutable action pins, read-only permissions, locked dependency + consumption, and opt-in external coverage reporting. +- Make publishing explicitly opt-in with a separate OIDC publishing job and document + required release/environment protections. +- Add operational trust-boundary, credential-handling, and sanitized-reporting guidance. ## [1.0.0] - 2026-05-19 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4ad4686..012e87a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,6 +10,13 @@ This project and everyone participating in it is governed by our [Code of Conduc ### Reporting Bugs +For suspected vulnerabilities or exposed credentials, use the private route in +[SECURITY.md](./SECURITY.md), not a public issue. Sanitize logs, notebooks, screenshots, +and traces before sharing; omit tokens, keys, local account names, identifying paths, +unnecessary personal identifiers, restricted data, and private operational details. +See [Credentials and Sensitive Outputs](./SECURITY.md#credentials-and-sensitive-outputs) +for the policy, placeholder examples, and permitted public attribution. + Before creating bug reports, please check the issue list as you might find out that you don't need to create one. When you are creating a bug report, please include as many details as possible: - **Use a clear and descriptive title** @@ -32,10 +39,10 @@ Enhancement suggestions are tracked as GitHub issues. When creating an enhanceme ### Pull Requests -- Follow the Python code style guidelines (see below) +- Follow the style and validation guidelines applicable to the changed artifacts - Document new code based on the Documentation Styleguide - End all files with a newline -- Avoid platform-dependent code +- Document platform-dependent behavior and the configurations actually tested - Add tests for any new functionality - Include appropriate commit messages @@ -87,10 +94,17 @@ Enhancement suggestions are tracked as GitHub issues. When creating an enhanceme ## Testing -- Write tests for all new features +- Add validation appropriate to new features or artifacts: code tests, schema fixtures, + skill checks, or documentation/example checks - Ensure all tests pass before submitting a pull request - Aim for high test coverage - Use descriptive test names +- Keep quick checks separate from network, paid API, accelerator, and scheduler tests. + State external calls and resource requirements before asking contributors to run them. +- Changes to CI must preserve least privilege: do not run untrusted PR code with + secrets, in privileged `pull_request_target`/`workflow_run` contexts, or on persistent + privileged runners. Pin actions to reviewed full commit SHAs, enforce dependency + locks in consuming jobs, and update pins deliberately. ## Guidelines for AI/LLM-Assisted Contributions diff --git a/README.md b/README.md index b165ac4..3845ac8 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,11 @@ This repository provides tools and resources that can serve as a template for ot BaseTemplate provides a foundation for creating new repositories following open-source best practices and the ModCon team's standards. +It provides a Python starter and a shared repository-quality baseline, not a required +language or directory layout. Existing projects should retain their structure and +qualified dependency stacks. Apply the requirements below to the artifacts a project +distributes; document justified non-applicability rather than adding unused scaffolding. + ## Features - Professional repository structure @@ -17,24 +22,26 @@ BaseTemplate provides a foundation for creating new repositories following open- ## Required Elements for ModCon Base Public Repositories -Every Base public repository must include the following elements to ensure quality, maintainability, and compliance with open-source standards: +Every Base public repository must address the following baseline. Python-specific +tools in this starter are examples, not consortium-wide requirements. ### License - An open-source license (Apache 2.0, MIT, or BSD recommended) - License file (`LICENSE`) clearly specifying the license terms -- License declaration in `pyproject.toml` or package metadata +- Consistent license declaration in package metadata, when distributing a package +- Attribution and third-party notices for redistributed code, data, and model assets ### Documentation -- A `docs/` folder with a proper documentation structure +- Discoverable, organized documentation (`docs/` is recommended when useful) - A comprehensive `README.md` at the repository root - Getting started guide and usage examples - API documentation (if applicable) ### Testing -- A test suite configured with pytest -- Tests in a `tests/` directory -- Coverage reporting configured (e.g., via pytest-cov) -- CI/CD integration to run tests automatically +- Validation appropriate to the repository: tests, schema/fixture checks, skill + validation, or documentation/example checks +- Documented commands and CI integration for those checks +- Coverage for executable code where meaningful; pytest and `tests/` are Python defaults ### Community Guidelines - `CONTRIBUTING.md` file with contribution guidelines @@ -42,27 +49,61 @@ Every Base public repository must include the following elements to ensure quali - `CODE_OF_CONDUCT.md` file outlining community standards - Clear procedures for reporting issues and submitting pull requests - Branch protection to ensure that sufficient review is being performed on anything going into `main` +- Private security-reporting guidance and safe handling of credentials and operational + data; see [Security Policy](./SECURITY.md) + +Sensitive-information handling is a review standard, not a requirement to duplicate +a sanitization policy in every repository. Review actual public artifacts using the +[shared guidance](./SECURITY.md#credentials-and-sensitive-outputs). Missing policy +wording alone is not a compliance failure. Link to shared guidance or add local +instructions only where the project's workflows need them. ### Project Metadata -- `pyproject.toml` with clear metadata including: - - Project name and description - - Author and contact information - - Dependencies and optional dependencies - - Supported Python versions - - Relevant classifiers +- Project name, purpose, maintainer/contact, and support status +- For packages, ecosystem-appropriate metadata (`pyproject.toml` for Python), including + dependencies, supported runtimes, and repository/documentation URLs ### Development Setup -- `Makefile` or equivalent build automation +- `Makefile`, scripts, or equivalent documented task commands - Clear instructions for setting up a development environment -- Dependencies documented in `pyproject.toml` with lock file (`uv.lock`) -- Example commands for linting, testing, and building +- Reproducible dependency setup appropriate to the project: lockfiles, pinned + requirements/images, or documented site-provided stacks +- Example commands for applicable validation and build tasks ### Acknowledgments - Acknowledgment of Genesis Mission support in the README - [Optional] Recognition of other funding sources +### Additional Requirements by Project Type + +Projects may fit more than one type. Small content repositories need not become packages. + +| Project type | Additional evidence | +| --- | --- | +| Library or CLI | Installation, tests, supported runtimes, and public interfaces | +| Agent skill or catalog | Client compatibility, tool permissions, external dependencies, installation/removal, and instruction/script validation | +| API or schema specification | Versioned contracts, fixtures, conformance checks, and breaking-change policy | +| Service, container, or HPC application | Runtime/trust boundary, deployment prerequisites, health checks, shutdown/cleanup, and tested platforms | +| Benchmark, model, or data workflow | Input provenance and rights, task/metrics, reference outputs, reproduction command, and resource needs | +| Tutorial or content | Prerequisites, validated walkthrough or content checks, attribution, and cleanup where applicable | + +### Support and Reproducibility + +Distinguish declared compatibility from configurations actually tested. Document +hardware, schedulers, system modules/native tools, accounts, and network requirements +where relevant. Identify downloads, external model/API calls, telemetry, charges, and +job submissions before users run the quick start. Provide a small smoke check and +separate expensive, network-dependent, or site-specific validation. + +For reproducible scientific results, record source and dependency revisions, +configuration, seeds, and input/model artifact identifiers or hashes. Passing portable +CI does not establish hardware qualification, scientific validity, or production readiness. + ## Quick Start +These commands and the supplied CI matrix apply to the Python starter. For adoption +and administrator setup, see [Getting Started](./docs/getting_started.md#adopting-the-template). + ### Prerequisites - Python 3.11 or higher diff --git a/SECURITY.md b/SECURITY.md index ba944ec..dd1e0b3 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -4,13 +4,19 @@ **Please do not report security vulnerabilities through public GitHub issues.** -Instead, please email your findings to modcon-base-code@lbl.gov. +Use GitHub private vulnerability reporting if enabled (Security -> Report a +vulnerability). Otherwise, email your findings to modcon-base-code@lbl.gov. Please include the following details in your report: - Description of the vulnerability - Steps to reproduce - Potential impact - Suggested fix (if available) +- Affected source revision or artifact version and relevant runtime configuration + +Share only sanitized, minimal evidence. Do not send live credentials, restricted +datasets, personal information, or sensitive prompts. For incidents on shared systems, +also follow the institution or HPC site's incident-response process. We will acknowledge receipt of your report within 48 hours and provide updates on progress towards a fix. @@ -21,6 +27,68 @@ We will acknowledge receipt of your report within 48 hours and provide updates o | 1.x | :white_check_mark: | | < 1.0 | :x: | +These contacts, response commitments, and supported versions describe BaseTemplate. +Adopting projects must replace them with a monitored reporting route and an accurate +support policy; unreleased projects should state which development revision receives fixes. + ## Security Updates We will release security updates as soon as possible after a vulnerability is confirmed. Affected users will be notified via GitHub security advisories. + +## Operational Guidance + +Apply the following controls where relevant and document project-specific boundaries. +This template does not qualify a deployment or replace institutional security policy. + +### Credentials and Sensitive Outputs + +This section provides shared guidance for authors and reviewers, not mandatory +policy text to copy into every repository. Assess actual artifacts and handling +practices; absence of equivalent wording is not itself a compliance failure. +Repositories may link here and add project-specific instructions where useful, +especially when collecting logs, traces, datasets, or user submissions. + +- Never commit credentials or restricted data, including in notebooks, generated job + scripts, model cards, screenshots, traces, or logs. Review artifacts before uploading. +- Before committing or sharing code, configuration, logs, notebooks, screenshots, + traces, or generated artifacts, remove tokens, API keys, passwords, private keys, + local account names, identifying filesystem paths, and unnecessary personal + identifiers. Use placeholders such as ``, ``, and `/path/to/data`. + Intentional public attribution, such as approved author names and maintainer + contacts, is permitted. +- Use scoped, short-lived credentials and approved secret storage. Ignore local secret + files and commit sanitized examples instead; ignore patterns are not access controls. +- Avoid tokens in command arguments, scheduler-exported environments, and generated + batch scripts. For file-based credentials, restrict permissions and follow site policy. +- If a credential is exposed, revoke/rotate it immediately and notify the responsible + operator privately. Removing the latest copy does not remove Git history or other + copies. Coordinate history cleanup after containment. + +### Agents, Models, and External Code + +- State which data goes to external model providers, telemetry, or trace stores, who + can access it, and how long it is retained. Make optional reporting explicit. +- Document tool authority and require approval for destructive, publishing, or costly + operations. Bound time, resource use, and job/API budgets. +- Treat retrieved documents, skill instructions, participant submissions, model + checkpoints, and dataset/configuration files as untrusted. Do not grant them authority + to override access policy or approve their own execution. +- Enforce least privilege and runtime isolation when executing untrusted code; prompts + and agent instructions are not a sandbox. Keep credentials and sensitive mounts out + of submission/evaluation environments and restrict network access where appropriate. +- Pin external code, images, and model assets to reviewed versions or immutable + identifiers; verify hashes and provenance where available. Loading pickle-backed + checkpoints or enabling remote model code can execute code and requires explicit trust. + +### Services and HPC + +- Declare whether deployment is localhost-only, trusted allocation-internal, or + externally accessible. Bind local demos to loopback; require appropriate + authentication, authorization, and TLS before widening access. +- Document persistent state, log redaction/retention, readiness, shutdown, and scoped + cleanup. Do not claim production or hardware support from portable CI alone. +- Preserve qualified site runtimes; do not silently replace accelerator/system stacks. + Run untrusted PR checks without deployment credentials or access to privileged runners. + +See [administrator setup](./docs/getting_started.md#administrator-setup) for GitHub +controls that must be enabled outside the repository. diff --git a/docs/faq.md b/docs/faq.md index 799380b..01145e8 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -65,7 +65,6 @@ Open a feature request on [GitHub](https://github.com/AI-ModCon/BaseTemplate/iss ### Who should I contact with questions? You can: -- Open a [GitHub Discussion](https://github.com/AI-ModCon/BaseTemplate/discussions) - Open an [Issue](https://github.com/AI-ModCon/BaseTemplate/issues) - Contact the ModCon base team diff --git a/docs/getting_started.md b/docs/getting_started.md index 8917b93..2e4c8fe 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -2,6 +2,61 @@ Welcome to BaseTemplate! This guide will help you get started with this project. +## Adopting the Template + +For a new repository, use the starter files that fit your project. For an existing +repository or organization transfer, apply the [baseline](../README.md#required-elements-for-modcon-base-public-repositories) +in place: preserve history, layout, interfaces, and qualified dependency stacks. + +- Replace template package names, URLs, contacts, acknowledgments, and support/version + statements with accurate project-specific values. Confirm the security contact and + response commitment before publishing them. +- Select the applicable requirements and document any non-applicability. Keep Python + package files, coverage, and the CI Python matrix only when appropriate. +- Review public artifacts against the shared + [sensitive-information guidance](../SECURITY.md#credentials-and-sensitive-outputs). + Do not require a separate sanitization policy in each repository. Links and local + reminders are optional; add workflow-specific instructions when useful. +- Adapt CI to the project's real validation commands. Pin external actions to reviewed + full commit SHAs and maintain those pins with dependency-update automation. +- The existing CI workflow checks spelling and local Markdown links/fragments on + pushes and pull requests. External URL checking is optional: manually run CI and + select `check_external_urls` to enable it (off by default). Results appear in the + job summary but do not fail the job or workflow, even if the checker itself errors. + External URL checks never run automatically. +- Keep external reporting opt-in. The CI example uploads coverage to Codecov only + when the repository variable `ENABLE_CODECOV` is `true`; review what is sent first. +- Publishing is opt-in. Remove the publish workflow for non-packages. For PyPI, first + configure a Trusted Publisher matching this repository, `publish.yml`, and the `pypi` + environment. Protect release tags and configure environment approval/release-tag + restrictions, then set the repository variable `ENABLE_PYPI_PUBLISH` to `true`. + The example builds on a published `v*` tag release and publishes those artifacts + from a separate OIDC-enabled job, without a long-lived API token. +- Document external calls, data flows, resource costs, and operational limits before + users run examples; see the [security guidance](../SECURITY.md#operational-guidance). + +### Administrator Setup + +Repository files do not enforce GitHub settings. An administrator should verify: + +- Required human approvals and status checks on the default branch, review ownership + for workflows and other sensitive paths (for example via `CODEOWNERS`), and restricted + bypass/force-push and release permissions. +- Private vulnerability reporting where available, a monitored fallback contact, + dependency alerts, secret scanning, and push protection. Review supported secret + patterns and permitted bypasses; scanners do not detect every secret. +- Least-privilege workflow permissions, approval for untrusted contributors, and no + untrusted PR execution on persistent or privileged HPC/self-hosted runners. +- Regular maintainer-access reviews and the organization's MFA policy. +- Protected publishing environments and release tags before enabling publication. + +Record which controls were verified, by whom, and when. A checked-in checklist is +not proof that live settings are enabled. + +## Python Starter Setup + +The following instructions apply to the included Python example. + ## Prerequisites - Python 3.11 or higher diff --git a/docs/index.md b/docs/index.md index 27af412..335a788 100644 --- a/docs/index.md +++ b/docs/index.md @@ -14,16 +14,16 @@ Welcome to the BaseTemplate documentation! - [Code of Conduct](../CODE_OF_CONDUCT.md) - Community standards - [License](../LICENSE) - Apache 2.0 License - [Changelog](../CHANGELOG.md) - Project history and changes +- [Security Policy](../SECURITY.md) - Private reporting and operational guidance ## Quick Links - [GitHub Repository](https://github.com/AI-ModCon/BaseTemplate) - [Issue Tracker](https://github.com/AI-ModCon/BaseTemplate/issues) -- [Discussions](https://github.com/AI-ModCon/BaseTemplate/discussions) ## Getting Help +- Report suspected vulnerabilities privately through [SECURITY.md](../SECURITY.md). - Check the [FAQ](./faq.md) - Search existing [GitHub Issues](https://github.com/AI-ModCon/BaseTemplate/issues) - Open a new [GitHub Issue](https://github.com/AI-ModCon/BaseTemplate/issues/new) -- Start a [Discussion](https://github.com/AI-ModCon/BaseTemplate/discussions/new) From db822e69e8d96173d58e7967d62e651b863ed2c7 Mon Sep 17 00:00:00 2001 From: Stefan Wild Date: Mon, 9 Nov 2026 12:30:02 -0800 Subject: [PATCH 3/4] Updated acknowledgment and checklist. --- README.md | 5 ++++- SECURITY.md | 7 +++++++ 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 3845ac8..2ca65d6 100644 --- a/README.md +++ b/README.md @@ -72,6 +72,7 @@ instructions only where the project's workflows need them. ### Acknowledgments - Acknowledgment of Genesis Mission support in the README +- Government disclaimer in the README - [Optional] Recognition of other funding sources ### Additional Requirements by Project Type @@ -150,7 +151,9 @@ We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for gu ## Support -This project acknowledges support from the U.S. Department of Energy (DOE), Office of Science, Office of Advanced Scientific Computing Research in alignment with DOE's Genesis Mission. +This material is based upon work supported by the U.S. Department of Energy (DOE), Office of Science, Office of Advanced Scientific Computing Research, as part of the Genesis Mission Platform. + +This Software was developed under funding from the U.S. DOE and the U.S. Government consequently retains certain rights. As such, the U.S. Government has been granted for itself and others acting on its behalf a paid-up, nonexclusive, irrevocable, worldwide license in the Software to reproduce, distribute copies to the public, prepare derivative works, and perform publicly and display publicly, and to permit others to do so. ## License diff --git a/SECURITY.md b/SECURITY.md index dd1e0b3..c216ca5 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -63,6 +63,13 @@ especially when collecting logs, traces, datasets, or user submissions. - If a credential is exposed, revoke/rotate it immediately and notify the responsible operator privately. Removing the latest copy does not remove Git history or other copies. Coordinate history cleanup after containment. +- Before making a repository or update public, review the full Git history and all + branches and tags that will be published for credentials and other sensitive + information. Use automated scanning where available and review its findings; a clean + scan does not prove that no sensitive information is present. If a credential is + found, revoke or rotate it immediately, then remove it from the history and verify + the cleanup with another scan before release. If it may already have been exposed, + follow the applicable incident-response process. ### Agents, Models, and External Code From 8b2a4a73ac9a0d3a5a9f364d9ec460c600890a33 Mon Sep 17 00:00:00 2001 From: Stefan M Wild Date: Mon, 9 Nov 2026 12:37:52 -0800 Subject: [PATCH 4/4] Update checkout reference to use current commit SHA Change checkout reference to use the current commit SHA instead of the release tag. Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- .github/workflows/publish.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 8bce6f6..6a60282 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -14,7 +14,7 @@ jobs: steps: - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 with: - ref: ${{ github.event.release.tag_name }} + ref: ${{ github.sha }} persist-credentials: false - name: Set up Python