diff --git a/docs/introduction/getting_started.md b/docs/introduction/getting_started.md index ddd2eca7..be85f33d 100644 --- a/docs/introduction/getting_started.md +++ b/docs/introduction/getting_started.md @@ -5,3 +5,91 @@ slug: /getting-started --- # Getting Started + +Welcome to **OpenPathfinder**, a collaborative open source initiative that empowers developers and organizations to secure, monitor, and manage their projects efficiently. This guide introduces you to our two flagship tools, **VisionBoard** and **fortSphere**, and helps you begin your journey with OpenPathfinder. + +--- + +![OpenPathfinder logo in header format](/img/openPathfinder_header.png) + +## What Is OpenPathfinder? + +OpenPathfinder is committed to building tools that: +- Simplify compliance with security and operational standards. +- Automate repetitive tasks, freeing up time for maintaining projects. +- Provide actionable insights to maintain project health. + +Our current projects: +- **[VisionBoard](#visionboard)**: A dashboard for data-driven compliance and project monitoring. +- **[fortSphere](#fortsphere)**: A CLI tool for secure policy management across GitHub organizations. + +--- + +![visionBoard logo in header format](/img/visionBoard_header.png) + +## VisionBoard + +VisionBoard helps organizations transform raw data into actionable insights. [Created to support OpenJS Foundation projects](/docs/history), it simplifies the complex task of monitoring security and operational health. + +### Key Features: +- **Customizable [Checks](/docs/visionBoard/Checks) and [Checklists](/docs/visionBoard/checklists)**: Automates compliance with security standards, such as the [OpenJS Security Compliance Guide](/docs/visionBoard/checklists#official-checklists). +- **Integration with Tools**: Connects to GitHub APIs, OSSF Scorecard, and other external sources to enrich and analyze data. +- **Intuitive Dashboards**: Offers visual insights into the state of your projects. + +VisionBoard is the go-to tool for organizations aiming to maintain compliance and ensure best practices across their repositories. Explore more on the [VisionBoard page](/docs/visionBoard). + +--- + +![fortSphere logo in header format](/img/fortSphere_header.png) + +## fortSphere + +fortSphere is a CLI tool that simplifies managing policies for GitHub organizations and repositories. Designed by maintainers, for maintainers, it ensures efficiency and security without compromising user control. + +### Key Features: +- **Local Processing**: All operations are executed locally—your sensitive data never leaves your machine. +- **Policy Management**: Detects and resolves non-compliant configurations with predefined or custom [policies](/docs/fortSphere/policies). +- **Real-Time Updates**: Provides instant feedback and remediation to secure your repositories. + +--- + +## Why Use OpenPathfinder? + +By combining VisionBoard and fortSphere, OpenPathfinder offers: +- **Comprehensive Solutions**: Address both compliance monitoring and secure policy enforcement. +- **Flexibility**: Use these tools independently or as part of an integrated workflow. +- **Community Focus**: Built collaboratively with a focus on practical needs. + +--- + +## Get Started + +1. **Learn More**: + - Dive into the [VisionBoard Overview](/docs/visionBoard) or [fortSphere Overview](/docs/fortSphere). + +2. **Join the Community**: + - Participate in discussions, explore issues, and contribute on [GitHub](https://github.com/OpenPathfinder). + +3. **Run Locally**: + If you prefer to start exploring the tools locally, use the following `docker-compose.yml` file: + + ```yml + # soon + ``` + +### Commands +- **Start the services**: + ```bash + docker compose up + ``` + +- **Stop and remove the services**: + ```bash + docker compose down + ``` + +This setup allows you to explore VisionBoard’s dashboard and fortSphere’s CLI in a local environment. + +--- + +Thank you for choosing OpenPathfinder. Together, we’re fortifying the future of open source development! diff --git a/docs/introduction/history.md b/docs/introduction/history.md new file mode 100644 index 00000000..36c7ff49 --- /dev/null +++ b/docs/introduction/history.md @@ -0,0 +1,173 @@ +--- +sidebar_position: 4 +title: History +slug: /history +--- + +# History of OpenPathfinder + +At OpenPathfinder, we believe that open source collaboration drives innovation and empowers communities to build sustainable solutions. Here’s how our journey began and evolved over time. + +--- + +OpenPathfinder emerged from a collective commitment to enhance the management and security of open source projects. It began as an initiative within the OpenJS Foundation's [Security Collaboration Space](https://github.com/openjs-foundation/security-collab-space), a forum dedicated to governing the security progress of JavaScript ecosystem projects. + +Initially, the team envisioned a "dashboard"—a dynamic tool to visualize the progress of projects adhering to the principles of the ["OpenJS Foundation Security Compliance Guide v1.0"](https://docs.google.com/document/d/1tvJYtptFXqvS4863dhPwoVmFT5Jwr_WZLralrnulCZs/edit?tab=t.0#heading=h.2waouzm4ry8i). This guide served as a foundation for security compliance best practices, emphasizing the importance of equipping maintainers with tools to address complex security requirements effectively. + +However, the team soon realized the potential to create a solution that transcended the limitations of a single ecosystem. This broadened the project’s scope into a platform capable of supporting diverse stacks and standards. The vision expanded from security compliance to improving the overall operational health of open source projects. Thus, OpenPathfinder was born—a universal solution designed to empower maintainers and foster sustainable project growth. + +A key principle in OpenPathfinder's design is ensuring **security and autonomy**. Both **VisionBoard** and **fortSphere**, the core tools of the platform, are self-hosted. This approach guarantees data security and provides maintainers with full control over their workflows and tools, eliminating reliance on third-party hosting and mitigating associated vulnerabilities. + +### Core Objectives of OpenPathfinder Tools: +- Automate compliance with security and operational standards. +- Deliver actionable insights for enhancing project health. +- Enable seamless policy management across distributed repositories. + +Built by maintainers for maintainers, OpenPathfinder embodies the spirit of collaboration, turning ambitious ideas into practical solutions that empower open source teams to thrive. + +--- + +## Milestones + +### 1. Initiate Development of Security Program Standards for OpenJS Projects (Feb 2024) + +In February 2024, [the OpenJS Foundation's Security Collaboration Space](https://github.com/openjs-foundation/security-collab-space) embarked on an ambitious initiative to [Develop Security Program Standards for OpenJS Projects](https://github.com/openjs-foundation/security-collab-space/issues/150). This project aimed to establish a comprehensive framework of security checks and guidelines to strengthen the security posture of OpenJS projects. + +Contributors conducted detailed analyses of existing standards and frameworks, ensuring the final program would address diverse maintainer needs while remaining actionable and effective. This collaborative effort resulted in a robust foundation for OpenPathfinder’s future tools and solutions. + +Key documents and discussions that shaped this initiative include: +- [Priority Group Index Page Options](https://hackmd.io/@rudd/H14K8eUuR): Explored ways to organize and prioritize security checks for accessibility. +- [Categories Index Options](https://hackmd.io/@rudd/BkUM3WU_R): Focused on categorizing security standards for easier understanding and implementation. +- [Priority Group Details Page Options](https://hackmd.io/@rudd/SyBtnZL_C): Discussed detailed layouts for presenting checks and recommendations. + +This milestone established a foundation for building adaptable security frameworks, paving the way for OpenPathfinder’s comprehensive solutions. + +--- + +### 2. Publish Draft of OpenJS Security Compliance Guide v1.0 (June 2024) + +By June 2024, the OpenJS Foundation achieved a significant milestone: the publication of the draft for the **OpenJS Security Compliance Guide v1.0**. This guide offered detailed insights and tools to help maintainers align their projects with best practices in security compliance. + +The draft included two key components: +1. **A comprehensive checklist spreadsheet** outlining actionable security checks and requirements for maintainers. +2. **A detailed guide** explaining how to apply these checks effectively to improve project security and operational health. + +Key resources from this milestone: +- [Issue #211 in Security Collaboration Space](https://github.com/openjs-foundation/security-collab-space/issues/211): Documented the progress and iterations of the compliance guide. +- [Intro and Review of Standards](https://docs.google.com/document/d/1tvJYtptFXqvS4863dhPwoVmFT5Jwr_WZLralrnulCZs/edit): A foundational document summarizing the goals and framework of the compliance guide. +- [Standards Checklist Spreadsheet](https://docs.google.com/spreadsheets/d/1GwIsAudAn89xv9DAbr1HUaY4KEVBsYfg--_1cW0uIB0/edit#gid=0): Detailed the list of checks maintainers could follow for compliance. + +#### Highlight: Interactive Introduction to the Compliance Guide + + + +This milestone marked a turning point, providing maintainers with actionable tools and a roadmap to navigate complex security landscapes effectively. The feedback and testing phases that followed refined the guide, ensuring its practical application across diverse open source projects. + +--- + +### 3. Website Launch (July 2024) + +While the original documents served as a strong foundation for discussion and feedback, they posed challenges for maintainers. The format required high familiarity with the compliance guide and was difficult to operationalize. To address these challenges, the team decided to build a website using **Docusaurus** to centralize and better organize the information for maintainers. + +The website grouped all the compliance information in an intuitive and accessible way, making it easier for maintainers to navigate and implement the guidelines. During this stage, the team synchronized updates with the original documents, incorporating community feedback in real-time. + + + + + + +The website was deployed on Netlify and is available at: [OpenJS Security Program Standards](https://openjs-security-program-standards.netlify.app/). + +This launch was a pivotal moment, transforming the compliance guide from a static resource into an interactive and dynamic tool that maintainers could easily use and refer to in their workflows. + +--- + +### 4. The "Dashboard" POC (November 2024) + +In the last quarter of 2024, thanks to support from [Alpha-Omega](https://alpha-omega.dev/), the team initiated the development of the "Dashboard" Proof of Concept (POC)—a long-discussed idea from earlier in the year. The goal was to build a basic POC within a few days to demonstrate how maintainers could efficiently analyze, understand, and address security issues. + +The POC leveraged local file storage, a CLI interface, and basic reporting and alert mechanisms using Markdown/JSON formats. It served as a proof of value, showing how this project could positively impact maintainers' daily workflows by streamlining security issue management. + +### Key Achievements: +- Successfully integrated external sources such as the GitHub API and the OSSF Scorecard. +- Analyzed data against predefined compliance checks from the guide. +- Showcased project progression using simple but effective visualizations. + +#### Highlight: Full Demo of the Dashboard + + + +Key Resources: +- **Slides**: [Presentation](https://slides.ulisesgascon.com/openjs-security-program-standards) +- **Code Repository**: [GitHub POC Code](https://github.com/UlisesGascon/poc-openjs-security-program-standards-dashboard) + +This milestone demonstrated the potential impact of the dashboard in simplifying security workflows, inspiring further iterations and community collaboration. + +--- + +### 5. OpenPathfinder and VisionBoard (December 2024) + +Following the success of the Dashboard POC, the team decided to formalize and expand its efforts. This led to the development of **[VisionBoard](/docs/visionBoard)**, the flagship tool under the broader [OpenPathfinder](https://openpathfinder.com/) initiative. [VisionBoard](/docs/visionBoard) aims to support maintainers with: +- Comprehensive compliance monitoring for multiple security guidelines or checklists. +- An extensible architecture for integration with various ecosystems and tools. +- Enhanced user interfaces designed for maintainers of all experience levels. + +To establish [OpenPathfinder](https://openpathfinder.com/) as an independent and scalable initiative, the team secured branding assets, including logos and domain names, while organizing the first contributors' meeting. This marked the beginning of VisionBoard's transition into a community-driven platform. + +Key Resources: +- **Slides**: (Coming Soon) +- **Recording**: (Coming Soon) + +--- + +### 6. fortSphere (December 2024) + +While [VisionBoard](/docs/visionBoard) excelled at providing insights into compliance, the team identified a critical gap: simplifying and accelerating the mitigation of security issues. To address this, they developed **[fortSphere](/docs/fortSphere)**, a CLI tool designed to: +- Apply security policies at the organization or repository level on GitHub. +- Streamline changes that typically require significant time and manual effort. +- Reduce the Time to Mitigation (TTM), especially for maintainers managing hundreds of repositories. + +[fortSphere](/docs/fortSphere) integrates seamlessly into existing workflows, making it an indispensable tool for maintainers aiming to achieve security compliance efficiently. + +Key Features: +- Centralized policy management for GitHub. +- A library of predefined [policies](/docs/fortSphere/policies) tailored to common security needs. +- Secure local operations for enhanced control and privacy. + + +## Our Future + +As OpenPathfinder evolves, we remain committed to: +- Expanding our toolset with new features and integrations. +- Engaging the open source community to drive innovation. +- Building a more secure and collaborative ecosystem for maintainers and developers. + +We invite you to join us on this journey. Whether you’re a contributor, a maintainer, or simply curious about our projects, OpenPathfinder welcomes you to help shape the future of open source. + +--- + +Thank you for being part of our story! \ No newline at end of file diff --git a/docs/projects/fortSphere/about.md b/docs/projects/fortSphere/about.md index a52c25c6..cae068c8 100644 --- a/docs/projects/fortSphere/about.md +++ b/docs/projects/fortSphere/about.md @@ -5,7 +5,6 @@ slug: /fortSphere --- -![fortSphere logo and tagline, 'Fortify your Digital Sphere, One Command at a Time](/img/fortSphere_header.png) # fortSphere @@ -13,9 +12,12 @@ Fortify your Digital Sphere, one command at a time --- -**fortSphere** is a community-driven, open-source CLI tool crafted with love by maintainers for maintainers. It empowers you to secure and streamline your GitHub organizations and repositories, ensuring you’re always in control. Built with a secure-by-default philosophy, fortSphere guarantees that: +![fortSphere logo and tagline, 'Fortify your Digital Sphere, One Command at a Time](/img/fortSphere_header.png) + + +**fortSphere** is a community-driven, open source CLI tool crafted with love by maintainers for maintainers. It empowers you to secure and streamline your GitHub organizations and repositories, ensuring you’re always in control. Built with a secure-by-default philosophy, fortSphere guarantees that: - **Your Tokens and Data Stay Local:** All operations are performed locally—your sensitive information never leaves your machine. -- **No Blind Trust Required:** As an open-source project, you don’t need to trust others—just the transparent and collaborative efforts of its contributors. +- **No Blind Trust Required:** As an open source project, you don’t need to trust others—just the transparent and collaborative efforts of its contributors. --- diff --git a/docs/projects/visionBoard/about.md b/docs/projects/visionBoard/about.md new file mode 100644 index 00000000..bcedae8d --- /dev/null +++ b/docs/projects/visionBoard/about.md @@ -0,0 +1,53 @@ +--- +sidebar_position: 1 +title: About +slug: /visionBoard +--- + +# VisionBoard + +Transforming Data into Actionable Insights + +--- + +![visionBoard logo and tagline, 'Transforming Data into Actionable Insights](/img/visionBoard_header.png) + +**visionBoard** helps organizations transform raw data into actionable insights. [Created to support OpenJS Foundation projects](/docs/history), it simplifies the complex task of monitoring security and operational health. + +--- + +## Key Features: + +- **Customizable [Checks](/docs/visionBoard/Checks) and [Checklists](/docs/visionBoard/checklists)**: Automates compliance with security standards, such as the [OpenJS Security Compliance Guide](/docs/visionBoard/checklists#official-checklists). Offers flexibility to define checks tailored to your project needs. +- **Integration with Tools**: Connects to GitHub APIs, OSSF Scorecard, and other external sources to enrich and analyze data. This ensures up-to-date and comprehensive insights. +- **Intuitive Dashboards**: Offers visual insights into the state of your projects, making it easier to identify trends, risks, and areas for improvement. + +--- + +## Demo Walkthrough + +Explore VisionBoard in action: + +1. **Monitor a Repository**: Learn how VisionBoard automates compliance checks for a GitHub repository. +2. **Analyze Results**: View insights from dashboards and reports generated by the system. +3. **Resolve Issues**: Identify actionable steps to improve security and compliance. + +*Coming soon: A detailed walkthrough video!* + +--- + +## Why visionBoard? + +VisionBoard helps organizations: + +- **Monitor Security and Health**: Track key metrics across repositories to ensure compliance and identify vulnerabilities in real time. +- **Automate Compliance**: Run predefined checks that align with industry standards, reducing manual effort and errors. +- **Save Time**: Generate actionable insights with minimal configuration, allowing teams to focus on critical tasks. + +**Example Use Case**: + +A team managing multiple open-source repositories uses VisionBoard to track branch protection settings and detect vulnerabilities across projects, reducing the time spent on manual reviews. + +--- + +Ready to transform your data into actionable insights? Explore our [Getting Started Guide](/docs/visionBoard/installation). diff --git a/docs/projects/visionBoard/architecture.md b/docs/projects/visionBoard/architecture.md new file mode 100644 index 00000000..ad90d601 --- /dev/null +++ b/docs/projects/visionBoard/architecture.md @@ -0,0 +1,83 @@ +--- +sidebar_position: 5 +title: Architecture +slug: /visionBoard/architecture +--- + +This project is part of the [openPathfinder](https://github.com/OpenPathfinder) initiative, playing a key role in data collection and analysis. This document outlines the architecture of visionBoard in detail. + +## Context + +![A flowchart with "Database" (yellow) bidirectionally connected to "visionBoard" (green), which sends data to "Website" (blue) via a one-way arrow.](/img/projects.svg) + +The [visionBoard](https://github.com/OpenPathfinder/visionBoard) project is designed to collect data from external sources, generate intelligence, and store information in a PostgreSQL database. Checks are run against the database to assess the health of projects. + +The collected data powers other projects, such as [this website](https://github.com/OpenPathfinder/openpathfinder.com), which presents compliance checks and reports. For integration details, see [this pipeline](https://github.com/OpenPathfinder/openpathfinder.com/blob/main/.github/workflows/sync_data.yml#L41). + +## Entities + +![A flowchart showing "Projects" (blue) connected to "GitHub Organizations" (green), which links to "GitHub Repositories" (yellow) in both directions.](/img/entities.svg) + +VisionBoard was [initially developed as "the dashboard" for the OpenJS Foundation](/docs/history), following their entity structure. Projects can span multiple GitHub Organizations, each containing several repositories. + +Enrichment is performed on repositories and organizations, while checks are executed at the project level and across other tables. + +### Database Schemas + +The SQL schema is available at [src/database/schema/schema.sql](https://github.com/OpenPathfinder/visionBoard/blob/main/src/database/schema/schema.sql). You can use external tools to visualize the database structure. + +## Internal Parts + +### Diagram + +![A flowchart showing "Database," "CLI," "artifacts," and external inputs connecting to "visionBoard Workflows" (Providers, Importers, Reporting, Checks, Scripts), with outputs to "Website" via GitHub Actions.](/img/visionBoard_architecture.svg) + +The CLI is the primary interface for interacting with visionBoard, supporting scripts via npm. Information is stored and retrieved from the database. Components like providers, importers, reporting, checks, and scripts operate in isolation for better testing and reusability. + +### Components + +#### CLI + +The CLI organizes actions into workflows and checks. Workflows automate steps like fetching data and updating the database. CLI commands and workflows are defined in [src/cli](https://github.com/OpenPathfinder/visionBoard/blob/main/src/cli) and [src/workflows](https://github.com/OpenPathfinder/visionBoard/blob/main/src/workflows). See [Usage](/docs/visionBoard/usage) for general usage instructions. + +#### Providers + +Providers are external data sources, such as the GitHub API. Providers retrieve data on repositories, organizations, and branches via HTTP APIs or containers (e.g., OSSF Scorecard). Data validation is performed before storage. See [src/providers](https://github.com/OpenPathfinder/visionBoard/blob/main/src/providers). + +#### Importers + +Importers bulk upsert curated project data. Data is JSON-validated using schemas in [src/schemas](https://github.com/OpenPathfinder/visionBoard/blob/main/src/schemas). Development details are in [this issue](https://github.com/OpenPathfinder/visionBoard/issues/56). + +#### Scripts + +Scripts, defined in [scripts](https://github.com/OpenPathfinder/visionBoard/tree/main/scripts), support integrations and query preparation. Future expansions will enhance developer experience (DevEx). + +#### Checks + +Checks analyze database information to evaluate project health (e.g., branch protection status). Key principles: + +- **Fast**: Use only database information, avoiding external queries or containers. +- **Isolated**: No interdependencies between checks. +- **Repeatable**: Consistent results for the same input. +- **Self-validating**: No manual interaction required. +- **Immutable**: Same input always produces the same output. + +For more details, see the [Checks Guide](/docs/visionBoard/Checks). + +#### Reporting + +Reports summarize check results, offering actionable insights like compliance status. Formats include JSON, Markdown, and HTML. For ongoing initiatives, see [this milestone](https://github.com/OpenPathfinder/visionBoard/milestone/4). + +For more details, see the [Report Management Documentation](/docs/visionBoard/report-management). + + +#### Database + +The PostgreSQL database structure supports querying and data enrichment. Management instructions are in [Database Management Documentation](/docs/visionBoard/database-management). The [src/store](https://github.com/OpenPathfinder/visionBoard/blob/main/src/store) contains database query methods. + +Testing resources include [__fixtures__](https://github.com/OpenPathfinder/visionBoard/blob/main/__fixtures__) and [__utils__](https://github.com/OpenPathfinder/visionBoard/blob/main/__utils__). + + +#### Artifacts + +Artifacts, such as JSON, Markdown, and HTML files, are generated for consumption by other tools and stored in the `output` directory (Git-ignored). VisionBoard focuses on artifact generation rather than presentation. diff --git a/docs/projects/visionBoard/checklists.md b/docs/projects/visionBoard/checklists.md index facd2407..f94ad850 100644 --- a/docs/projects/visionBoard/checklists.md +++ b/docs/projects/visionBoard/checklists.md @@ -1,5 +1,5 @@ --- -sidebar_position: 3 +sidebar_position: 9 title: Checklists slug: /visionBoard/checklists --- diff --git a/docs/projects/visionBoard/checks.md b/docs/projects/visionBoard/checks.md index 210641fd..422f64ff 100644 --- a/docs/projects/visionBoard/checks.md +++ b/docs/projects/visionBoard/checks.md @@ -1,5 +1,5 @@ --- -sidebar_position: 2 +sidebar_position: 8 title: Checks slug: /visionBoard/Checks --- diff --git a/docs/projects/visionBoard/configuration.md b/docs/projects/visionBoard/configuration.md new file mode 100644 index 00000000..c3ae2e69 --- /dev/null +++ b/docs/projects/visionBoard/configuration.md @@ -0,0 +1,72 @@ +--- +sidebar_position: 3 +title: Configuration +slug: /visionBoard/configuration +--- + +## Secrets Management + +Both the GitHub token and database credentials are considered sensitive information. You can manage these secrets using environment variables or `.env` files for [local development](/docs/visionBoard/installation#from-source-code). Here’s a unified guide on handling these secrets: + +### Environment Variables + +Set secrets as environment variables directly in your shell or environment configuration. For example: + +- **Database Secrets**: + - `DB_HOST`: Database host + - `DB_USER`: Database user + - `DB_PASSWORD`: User password + - `DB_NAME`: Database name + - `DB_SSL`: Enable SSL (optional, defaults to `false` if not set). + +- **GitHub Token**: + - `GITHUB_TOKEN`: Token with at least `repo:read` permissions (or `admin:read` for enhanced functionality). + +### Using a `.env` File + +For [local development](/docs/visionBoard/installation#from-source-code), you can use a `.env` file to centralize secrets management. The `.env` file stores environment variables in a key-value format, making them easy to load into your application. + +Here’s an example `.env` file: + +```env +DB_HOST=localhost +DB_USER=postgres +DB_PASSWORD=securepassword +DB_NAME=visionboard +DB_SSL=false +GITHUB_TOKEN=your_github_token +``` + +Load this file into your application using the following command: + +```bash +node --env-file=.env visionboard.js workflow run --name +``` + +:::note + +Avoid storing sensitive data like passwords in plaintext `.env` files in production. Instead, consider using tools like HashiCorp Vault or AWS Secrets Manager for secure management. + +::: + +### Docker Secrets Injection + +When using Docker, inject secrets via the `-e` flag or use a `.env` file with `--env-file`. Examples: + +- **Injecting manually**: + + ```bash + docker run --rm \ + -e DB_HOST=localhost \ + -e DB_USER=postgres \ + -e DB_PASSWORD=securepassword \ + -e GITHUB_TOKEN=mytoken \ + ghcr.io/openpathfinder/visionboard:latest workflow run --name + ``` + +- **Using a `.env` file**: + + ```bash + docker run --rm --env-file=.env \ + ghcr.io/openpathfinder/visionboard:latest workflow run --name + ``` diff --git a/docs/projects/visionBoard/database_management.md b/docs/projects/visionBoard/database_management.md new file mode 100644 index 00000000..139c3491 --- /dev/null +++ b/docs/projects/visionBoard/database_management.md @@ -0,0 +1,61 @@ +--- +sidebar_position: 7 +title: Database Management +slug: /visionBoard/database-management +--- + +This project requires a PostgreSQL instance to store and query data. Some commands do not require this dependency. The project uses [Knex](https://knexjs.org/) to handle database connections and maintenance activities, such as [seeds](https://knexjs.org/guide/migrations.html#seed-files), [migrations](https://knexjs.org/guide/migrations.html), and [rollback](https://knexjs.org/guide/migrations.html#rollback) of changes. + +Knex works transparently for most users, but if you want to contribute by solving a bug or adding a new feature, it’s important to be familiar with these steps. + +:::note +These commands are relevant only for [local development](/docs/visionBoard/installation#from-source-code) using npm. They are not applicable when using Docker. +::: + +## Schema Management + +Schema management involves maintaining the database structure. Use the following commands: + +- **Check the schema**: Refer to the latest schema file at [/src/database/schema/schema.sql](https://github.com/OpenPathfinder/visionBoard/blob/main/src/database/schema/schema.sql). + +- **Update the schema**: Generate a new schema file based on the current database state: + + ```bash + npm run db:generate-schema + ``` + +This ensures the schema file reflects the latest changes applied to the database. + +## Migrations + +Migrations manage incremental changes to the database schema, ensuring consistency across environments. Use these commands: + +- **Run latest migrations**: Apply all pending migrations to update the database schema: + + ```bash + npm run db:migrate + ``` + +- **Rollback migrations**: Undo the most recent migration: + + ```bash + npm run db:rollback + ``` + +Rollbacks are useful for undoing changes if a migration introduces unintended issues. + +## Seeding + +Seeding populates the database with predefined data, which is especially useful for testing or development environments: + +- **Seed the database**: Populate the database with seed data: + + ```bash + npm run db:seed + ``` + +For more details on seeding, refer to the [Knex documentation](https://knexjs.org/guide/migrations.html#seed-files). + +--- + +If you encounter any issues with these commands, ensure your database connection is configured correctly and verify that the necessary environment variables are set. Check the [Configuration guide](/docs/visionBoard/configuration) for additional information. diff --git a/docs/projects/visionBoard/index.md b/docs/projects/visionBoard/index.md deleted file mode 100644 index 0581b262..00000000 --- a/docs/projects/visionBoard/index.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -sidebar_position: 1 -title: visionBoard -slug: /visionBoard ---- - -# visionBoard - -Lorem Ipsum \ No newline at end of file diff --git a/docs/projects/visionBoard/installation.md b/docs/projects/visionBoard/installation.md new file mode 100644 index 00000000..03fc789d --- /dev/null +++ b/docs/projects/visionBoard/installation.md @@ -0,0 +1,85 @@ +--- +sidebar_position: 2 +title: Installation +slug: /visionBoard/installation +--- + +# Installation Guide for visionBoard + + +This guide outlines multiple methods to install visionBoard. After installation, you can verify that the binary is working correctly by running the `version` command. The console output should resemble: + +``` +[08:36:40.532] INFO: visionBoard@0.1.0-beta2 (MIT) +``` + +## Install via npm + +You can install visionBoard globally using npm: + +```bash +npm i -g visionBoard +visionBoard version +``` + +Alternatively, use it directly with `npx`: + +```bash +npx visionBoard version +``` + +## Using Docker + +To use visionBoard via Docker: + +1. Pull the Docker image: + + ```bash + docker pull ghcr.io/openpathfinder/visionboard:latest + ``` + +2. Run the container and check the version: + + ```bash + docker run --rm ghcr.io/openpathfinder/visionboard:latest version + ``` + +3. (Optional) Create an alias for convenience: + + ```bash + alias visionBoard="docker run --rm ghcr.io/openpathfinder/visionBoard:latest" + ``` + +## From Source Code + +To install visionBoard from source: + +1. Clone the repository: + + ```bash + git clone https://github.com/OpenPathfinder/visionBoard.git + ``` + +2. Navigate to the project directory: + + ```bash + cd visionBoard + ``` + +3. Install dependencies: + + ```bash + npm install + ``` + +4. Verify the installation: + + ```bash + node visionboard.js version + ``` + +5. (Optional) Create an alias for convenience: + + ```bash + alias visionBoard="node visionBoard.js" + ``` diff --git a/docs/projects/visionBoard/report_management.md b/docs/projects/visionBoard/report_management.md new file mode 100644 index 00000000..a431f216 --- /dev/null +++ b/docs/projects/visionBoard/report_management.md @@ -0,0 +1,35 @@ +--- +sidebar_position: 6 +title: Report Management +slug: /visionBoard/report-management +--- + + +visionBoard has the capability of generating reports that can be used to analyze data. + +## Generate the Reports + +_Not yet implemented_ + +## Showcase the Reports + +The simplest option is to run the workflow `show-reports`, which will start an HTTP server that lists the content in the `output` folder. Any asset previously generated can be accessed via a web browser using this approach. + +### Static Server + +visionBoard includes the option to run a local HTTP server to serve the artifacts generated during its processes. This allows easy access to outputs without needing external hosting. + +You can customize the server by defining the following environment variables: + +- `IP`: The IP address the server should bind to (default: `localhost`). +- `PORT`: The port the server should use (default: `3000`). + +For example, to run the server on a specific IP and port: + +```bash +export IP=192.168.1.100 +export PORT=8080 +visionBoard workflow run --name show-reports +``` + +If these variables are not set, visionBoard will default to `localhost:3000`. \ No newline at end of file diff --git a/docs/projects/visionBoard/usage.md b/docs/projects/visionBoard/usage.md new file mode 100644 index 00000000..56270c80 --- /dev/null +++ b/docs/projects/visionBoard/usage.md @@ -0,0 +1,146 @@ +--- +sidebar_position: 4 +title: Usage +slug: /visionBoard/usage +--- + +## CLI Commands + +Every command in `visionBoard` comes with its own detailed help documentation. Use the `help` command to get more information about specific commands and their options. For example: + +- General help: + ```bash + visionBoard help + ``` + +- Command-specific help: + ```bash + visionBoard workflow help + ``` + +### Version + +Display the current version of visionBoard. Use this command to verify your installation and ensure compatibility: + +```bash +visionBoard version +``` + +### Projects + +The `visionBoard project` command allows you to add and manage projects linked to `visionBoard`. In the [architecture documentation](/docs/visionBoard/architecture) you can get a better idea of how the entities are related (project, organization, repository, etc...) + +#### Add a New Project + +Use this command to add a project with one or multiple GitHub organizations associated to the visionBoard: + +```bash +visionBoard project add [--name ] [--github-urls ] +``` + +- **`--name `**: The name you want to assign to this project. +- **`--github-urls `**: One or more GitHub organization URL(s) associated with the project. + +**Example**: + +```bash +visionBoard project add --name express --github-urls https://github.com/expressjs https://github.com/pillarjs https://github.com/jshttp +``` + +This command adds a project named `express` and associates it with three GitHub organizations. + +For more details about project configuration, see the [architecture documentation](/docs/visionBoard/architecture). + +### Workflows + +Workflows in `visionBoard` automate sequences of tasks or checks. Use the following commands to manage workflows: + +#### Run a Workflow + +Execute a specific workflow by name: + +```bash +visionBoard workflow run [--name ] +``` + +**Example**: + +```bash +visionBoard workflow run --name run-all-checks +``` + +#### List Available Workflows + +Display all available workflows: + +```bash +visionBoard workflow list +``` + +### Checks + +Checks are individual tasks or validations performed by `visionBoard`. Use the following commands to manage checks: + +#### List All Available Checks + +Display a list of all available checks: + +```bash +visionBoard check list +``` + +For more details about checks available, see the [Checks documentation](/docs/visionBoard/Checks). + +#### Run a Specific Check + +Execute a specific check by name: + +```bash +visionBoard check run [--name ] +``` + +#### Run All Checks Sequentially + +Run all checks in sequence using a predefined workflow: + +```bash +visionBoard workflow run run-all-checks +``` + +For more details about checks, see [Checks Guide](/docs/visionBoard/Checks). + +### Checklists + +Checklists are collections of checks grouped for convenience. Use these commands to manage and execute checklists: + +#### List Available Checklists + +Display all available checklists: + +```bash +visionBoard checklist list +``` + +#### Run a Specific Checklist + +Execute a specific checklist by name: + +```bash +visionBoard checklist run [--name ] +``` + +#### Run a Checklist with a Defined Project Scope + +Run a checklist while limiting its scope to specific projects: + +```bash +visionBoard checklist run [--name ] [--project-scope ] +``` + +**Example**: + +```bash +visionBoard checklist run --name OpenJS-SCGv1.0-active --project-scope express +``` + +For more details about checklists, see [Checklists Guide](/docs/visionBoard/checklists). diff --git a/docusaurus.config.js b/docusaurus.config.js index e4d54b11..4c90e4a1 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -83,6 +83,8 @@ const config = { // {to: '/docs/projects/fortSphere', label: 'fortSphere', position: 'left'}, // {to: '/docs/projects/visionBoard', label: 'visionBoard', position: 'left'}, {to: '/blog', label: 'Blog', position: 'left'}, + {to: '/contribute', label: 'Contribute', position: 'left'}, + {to: '/support', label: 'Support', position: 'left'}, { href: 'https://github.com/openPathfinder/openpathfinder.com', label: 'GitHub', diff --git a/src/pages/code_of_conduct.md b/src/pages/code_of_conduct.md new file mode 100644 index 00000000..a91ec6a0 --- /dev/null +++ b/src/pages/code_of_conduct.md @@ -0,0 +1,133 @@ + +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the overall + community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or advances of + any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email address, + without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official email address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +ulises@linux.com. +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. + +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at +[https://www.contributor-covenant.org/translations][translations]. + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations \ No newline at end of file diff --git a/src/pages/contribute.md b/src/pages/contribute.md index 04b0095e..717e7d0b 100644 --- a/src/pages/contribute.md +++ b/src/pages/contribute.md @@ -2,4 +2,165 @@ title: Contribute --- -# Contribute \ No newline at end of file +## Before Anything + +The project welcomes all contributions from anyone willing to work in good faith with other contributors and the community. No contribution is too small, and all contributions are valued. **Any contribution to this project must follow the [Code of Conduct](#code-of-conduct) and the [DCO](#developers-certificate-of-origin-11).** + +--- + +## Code of Conduct + +The project has a [Code of Conduct](/code_of_conduct) to which all contributors must adhere. This ensures a respectful and inclusive environment for everyone involved. + +--- + +## Developer's Certificate of Origin 1.1 + +```text +By making a contribution to this project, I certify that: + + (a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + + (b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + + (c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + + (d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` + +--- + +## Supporting the Project + +We are committed to providing tools that empower developers and organizations. However, building and maintaining open-source software requires resources. If you find value in our tools, consider supporting the project through donations. + +### How You Can Help + +- **Individual Donations**: Contributions of any size are welcome and help us continue our work. +- **Corporate Sponsorship**: If you represent a company, you can sponsor the project and gain recognition while supporting the open-source community. + +For more details, visit our [Sponsorship Page](/support). + +--- + +## Where to Contribute + +:::tip + +Any issue labeled [help wanted](https://github.com/search?q=org%3AOpenPathfinder+label%3A%22help+wanted%22+state%3A"open"&type=issues) or [good first issue](https://github.com/search?q=org%3AOpenPathfinder+label%3A%22good+first+issue%22+state%3A"open"&type=issues) is a great opportunity to help the project. + +::: + +Contributions can take many forms, from improving documentation to fixing bugs or adding features. Below are specific areas to focus your contributions: + +### Website + +Contribute by improving documentation, user guides, and resources hosted on the [OpenPathfinder website](https://openpathfinder.org). Typical contributions include: + +- Adding or editing guides. +- Fixing typos and broken links. +- Enhancing readability and accessibility. + +### fortSphere + +Help improve the CLI by: + +- Adding new commands. +- Enhancing existing policies. +- Fixing bugs or optimizing performance. +- Expanding test coverage. + +### visionBoard + +VisionBoard contributions can include: + +- Writing or improving documentation. +- Adding new compliance checks. +- Enhancing dashboards or reports. +- Answering user questions or providing community support. +- Running infrastructure and advocating for the project. + +--- + +## Pull Requests + +### Creating a Good PR + +Follow these steps to create a high-quality Pull Request (PR): + +1. **Understand the Guidelines:** + - Read the [Contributing Guidelines](/contribute). + - Adhere to the [Code of Conduct](/code_of_conduct). +2. **Before You Start:** + - Link your PR to an issue if it addresses a bug or feature request. + - Sync with the main branch to avoid conflicts. + - Focus on one issue or feature per PR. +3. **Writing the Code:** + - Follow [coding standards](https://standardjs.com/). + - Write or update tests to cover your changes. + - Keep changes minimal and avoid unrelated edits. +4. **Writing the PR:** + - Use a descriptive title. + - Provide a detailed description, including **what**, **why**, and **how**. + - Link related issues (e.g., `Closes #123`). +5. **Checklist Before Submission:** + - [ ] Code is linted and passes style checks. + - [ ] Tests are added, updated, and pass. + - [ ] Documentation is updated (if applicable). + - [ ] Branch is up-to-date with main. +6. **Engage with Feedback:** + - Respond to comments promptly and revise as needed. + - Check CI results and address any failures. + +--- + +## Current Initiatives + +### Solve Technical Debt + +Contribute to the project by solving [technical debt issues](https://github.com/search?q=org%3AOpenPathfinder+label%3A%22technical-debt%22+state%3A"open"&type=issues), especially those tagged as [good first issue](https://github.com/search?q=org%3AOpenPathfinder+label%3A%22good+first+issue%22+state%3A"open"&type=issues). + +### Research on Compliance Checks for visionBoard + +Help by researching compliance checks, defining implementations, and suggesting improvements. Look for issues tagged [compliance-checks + research-needed](https://github.com/OpenPathfinder/visionBoard/issues?q=sort%3Aupdated-desc+is%3Aissue+is%3Aopen+label%3Acompliance-checks+label%3Aresearch-needed). + +### Add Compliance Checks for visionBoard + +Follow these steps to implement compliance checks: + +- **1. Define a Good Implementation ([Example](https://github.com/OpenPathfinder/visionBoard/issues/43#issuecomment-2524594504)):** + - Read the documentation (guidelines, best practices, etc.). + - Brainstorm the implementation details (logic, alerts, tasks, validations, edge cases, etc.). + - Reach an agreement on the implementation details before starting. +- **2. Update Check Record ([Example](https://github.com/OpenPathfinder/visionBoard/commit/55eaac59920a5229ef9eeaf859943578a66d1aeb)):** + - Update the `compliance_checks` row with fields like `how_to_url`, `implementation_status`, `implementation_type`, and `implementation_details_reference`. + - Test migration scripts using `npm run db:migrate` and `npm run db:rollback`. + - Update the database schema with `npm run db:generate-schema`. +- **3. Implement the Business Logic ([Validator Example](https://github.com/OpenPathfinder/visionBoard/commit/44c41d119f0daefb7b2e496ba35d5ab65bcc319b) and [Check Example](https://github.com/OpenPathfinder/visionBoard/commit/6f1e16129ee0d01a1b9b536cd2dc6090b048b71f)):** + - Add the specific validator in `src/checks/validators/index.js`. + - Add the check logic in `src/checks/complianceChecks`. + - Calculate `severity` accurately (`getSeverityFromPriorityGroup`). + - Update relevant database tables (`compliance_checks_alerts`, `compliance_checks_tasks`, `compliance_checks_results`). +- **4. Ensure It Works as Expected:** + - Add unit tests for the validator check. + - Add integration test cases for the check. + - Verify all tests pass. + - Run `check run --name {check_code_name}` and verify database changes. Update the seed script if necessary (`npm run db:seed`). +- **5. Update the Website ([Example](https://github.com/OpenPathfinder/website/pull/9)):** + - Review content at `https://openjs-security-program-standards.netlify.app/details/{check_code_name}`. + - Create a PR to include check calculation details and mitigation information. + diff --git a/src/pages/sponsors.md b/src/pages/sponsors.md deleted file mode 100644 index b0c37ad8..00000000 --- a/src/pages/sponsors.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: Sponsors ---- - -# Sponsors \ No newline at end of file diff --git a/src/pages/support.md b/src/pages/support.md new file mode 100644 index 00000000..ef81fb92 --- /dev/null +++ b/src/pages/support.md @@ -0,0 +1,33 @@ +--- +title: Support +--- + +# Support OpenPathfinder + +OpenPathfinder is an open source initiative powered by a passionate community. Your support sustains this project and fuels the development of impactful tools that benefit developers and organizations worldwide. + +--- + +## Why Support? + +Your contribution: + +- **Fuels Innovation**: Helps maintain and improve open source tools. +- **Empowers Growth**: Supports the creation of new initiatives in the open source ecosystem. +- **Creates Impact**: Directly benefits the community through valuable projects. + +--- + +## How to Support + +### Individual Donations +Every contribution matters! Visit my [GitHub Sponsors Page](https://github.com/sponsors/UlisesGascon) to donate. + +### Corporate Sponsorships +Tailored sponsorship packages include benefits like priority support and personalized features. Check out my [GitHub Sponsors Page](https://github.com/sponsors/UlisesGascon) or contact me at [ulises@linux.com](mailto:ulises@linux.com). + +--- + +## Have Questions? + +Feel free to reach out at [ulises@linux.com](mailto:ulises@linux.com). Together, we can build a stronger open source future! diff --git a/static/img/entities.svg b/static/img/entities.svg new file mode 100644 index 00000000..c3409faa --- /dev/null +++ b/static/img/entities.svg @@ -0,0 +1,11 @@ + + + + + + + + + ProjectsGitHubOrganizationsGitHubRepositories \ No newline at end of file diff --git a/static/img/openPathfinder_header.png b/static/img/openPathfinder_header.png new file mode 100644 index 00000000..57ebb020 Binary files /dev/null and b/static/img/openPathfinder_header.png differ diff --git a/static/img/projects.svg b/static/img/projects.svg new file mode 100644 index 00000000..502f81dc --- /dev/null +++ b/static/img/projects.svg @@ -0,0 +1,11 @@ + + + + + + + + + visionBoardWebsiteDatabase \ No newline at end of file diff --git a/static/img/visionBoard_architecture.svg b/static/img/visionBoard_architecture.svg new file mode 100644 index 00000000..8268556b --- /dev/null +++ b/static/img/visionBoard_architecture.svg @@ -0,0 +1,11 @@ + + + + + + + + + WebsiteDatabaseartifactsGithub ActionsProvidersImportersvisionBoard - WorkflowsExternalAPIsFormsdataChecksReportingScriptsCLIContainers \ No newline at end of file diff --git a/static/img/visionBoard_header.png b/static/img/visionBoard_header.png new file mode 100644 index 00000000..d94050bf Binary files /dev/null and b/static/img/visionBoard_header.png differ diff --git a/static/img/visionBoard_profile.png b/static/img/visionBoard_profile.png index 75354c0e..29a82a51 100644 Binary files a/static/img/visionBoard_profile.png and b/static/img/visionBoard_profile.png differ