Overview

We need a standard markdown "learn more" doc for the "Nuget install scripts" rule.

Additional context

It should follow the same format and style as the rest of the analytics docs. The doc should be called "nuget_install_scripts.md" to match the existing published link from the rule.

Acceptance Criteria

• The "Learn More" page is hosted at https://docs.phylum.io/analytics/nuget_install_scripts
• The "Issue Tags" page is updated with an entry and link to the new page
• A redirect entry is added to account for renaming the page from nuget_install_scripts_rule

Overview

We need a standard markdown "learn more" doc for the "Ruby install hooks" rule.

Additional context

It should follow the same format and style as the rest of the analytics docs. The doc should be called "ruby_install_hooks.md" to match the existing published link from the rule.

Acceptance Criteria

• The "Learn More" page is hosted at https://docs.phylum.io/analytics/ruby_install_hooks
• The "Issue Tags" page is updated with an entry and link to the new page

Overview

Provide simple instructions that a Netskope subscriber can follow to get set up to use Phylum malicious package hash list.

Story

This is part of https://github.com/phylum-dev/roadmap/issues/385

Overview

Add a new content overview page for the "Defend Your Workstation" topic/concept. It will be less of a guide and meant more as a landing page to drive folks to the appropriate local protection method. This is meant to answer the question of how Phylum can defend the developer by shifting security even further left.

Additional context

Provide more detail around the new content:

• The page will be a new landing page
  • The content will be action oriented, with more detail and distinction made about the context (local development) within which those integrations exist
  • Provide a compelling user story to help sell the value offered by the integrations
• Cover all of the current options
  • Direct CLI use
  • "pre-check" default extensions
  • Git pre-commit hook
  • Optional CLI extensions
• Step through the process to make it as clear as possible
  • It should be possible for someone with no knowledge of Phylum to read through one of these pages and follow along to completion
• A single page is okay for now
  • Move to the "self-identify" (e.g., tile based decision tree) model later, with individual pages/docs for each combination
• Get more guidance from @furi0us333 and/or the marketing team

Overview

Add a new content overview page for the "Defend Your Application" topic/concept. It will be less of a guide and meant more as a landing page to drive folks to the appropriate CI/CD integration.

Additional context

Provide more detail around the new content:

• The page will be like the current Integrations Overview page
  • It might also simply re-use that existing page
  • The content will be action oriented, with more detail and distinction made about the context (CI platforms) within which those integrations exist
  • Provide a compelling user story to help sell the value offered by the integrations
• Simple links are okay for now
  • Icons/graphics would be nice
  • Move to the "self-identify" (e.g., tile based decision tree) model later
• Get more guidance from @furi0us333 and/or the marketing team

Overview

Add a new integration guide for Tines.

Additional context

Provide more detail around the new content:

• The content will be like the "Other integrations" currently linked from the integrations overview page
  • Get the details/content from someone with access to it (@furi0us333 or @louislang, maybe)
• The page name could be Tines Integration
• The address/slug could be
  • https://docs.phylum.io/docs/tines now for Readme.com
  • https://docs.phylum.io/docs/integrations/tines going forward for Docusaurus

Description

Move pages from the phylum-dev/cli repo to the phylum-dev/documentation repo.

Additional Details

• Pages to move are identified in #24
• Coordinate the addition of pages with a corresponding removal from the source repo
• Keep the same frontmatter and file/page names
• Create a directory structure that makes sense for the receiving repo
• The content should not change at this time
  • There will be future issue(s) to clean up and normalize the content

Acceptance Criteria

• Pages exist in phylum-dev/documentation repo
• Pages have been removed from phylum-dev/cli repo

Automate updates for:

• Dependencies
• GitHub Actions
• pre-commit hooks, if used

Overview

We need a standard markdown "learn more" doc for the "High entropy blobs" rule.

Additional context

It should follow the same format and style as the rest of the analytics docs. The doc should be called "high_entropy_blobs.md" to match the existing published link from the rule.

Acceptance Criteria

• The "Learn More" page is hosted at https://docs.phylum.io/analytics/high_entropy_blobs
• The "Issue Tags" page is updated with an entry and link to the new page

Overview

We need a standard markdown "learn more" doc for the "Deprecated Package" rule.

Additional context

It should follow the same format and style as the rest of the analytics docs. The doc should be called "deprecated_package.md".

Acceptance Criteria

• The "Learn More" page is hosted at https://docs.phylum.io/analytics/deprecated_package
• The "Issue Tags" page is updated with an entry and link to the new page

Overview

An integration for Phylum exists in the Sophos Factory; we should write documentation on how to install and use that integration.

Overview

As we migrate away from Readme.com, we may need a Phylum API reference on the new Phylum doc site.

Specifically, customers have found the code snippets from Readme.com to be very useful. Here is an example:

Additional context

There are at least two options that Docusaurus advertises in their Community Features section

• redocusaurus - A Docusaurus preset for integrating OpenAPI documentation into your docs with Redoc
• docusaurus-openapi-docs - A Docusaurus v2 plugin and theme for generating interactive OpenAPI docs

Description

Update existing license issue to reflect an issue where using a package in a commercial product is prohibited.
Add new issue when a specific license requires source code distribution.

Overview

Policy provided by Phylum, and its application, have changed enough to benefit from a documentation overview. Perhaps it's a good idea to add a page on Phylum-provided policies and how are they being applied out of the box.

Additional context

screen recording that shows the user hoe to explore phylum regos
video

Overview

The EvalCalls rule is getting put back into prod and will need an accompanying docs page.

Additional context

It should follow the same format and style as the rest of the analytics docs. The doc should be called "eval_calls.md".

Acceptance Criteria

• The "Learn More" page is hosted at https://docs.phylum.io/analytics/eval_calls
• The "Issue Tags" page is updated with an entry and link to the new page

Description

Move pages directly hosted on Readme.com to the phylum-dev/documentation repo.

Additional Details

• Pages to move are identified in #24
• Coordinate the addition of pages with a corresponding removal from Readme.com
  • This may not be necessary if the page has the same metadata
  • This may require assistance from @furi0us333
• Keep the same frontmatter and file/page names
• Create a directory structure that makes sense for the receiving repo
• The content should not change at this time
  • There will be future issue(s) to clean up and normalize the content

Acceptance Criteria

• Page content exists in phylum-dev/documentation repo

Overview

We need a standard markdown "learn more" doc for the newly introduced Malware Bazaar hash check rule.

Acceptance Criteria

• The "Learn More" page is hosted at https://docs.phylum.io/analytics/malware_bazaar_check
• The "Issue Tags" page is updated with an entry and link to the new page

Add a CODEOWNERS file to automate the assignment of PR reviewers. Do this after the repo has been configured and a steady state is reached where most of the PRs are documentation updates. The likely entry for the file is @phylum-dev/engineering, but a larger/different audience is possible.

Enforce this by updating the branch protection rule to "Require review from Code Owners."

Change the custom domain for Docusaurus based Phylum docs from docs-stg.phylum.io to docs.phylum.io. Do this after all other work is completed to move from Readme.com to Docusaurus.

• Full directions
  • Update the settings
  • Update the CNAME file in the default branch (or branch hosting the pages)
  • Update the CNAME record with the DNS provider

Overview

Add a new integration guide for the existing Phylum GitHub App.

Additional context

Provide more detail around the new content:

• The content will be like the "Current integrations" currently linked from the integrations overview page
  • The current link there should be updated to point to this new guide
• The page name could be GitHub App Integration
• The address/slug could be
  • https://docs.phylum.io/docs/github_app now for Readme.com
  • https://docs.phylum.io/docs/integrations/github_app going forward for Docusaurus
• Include screenshots to walk through the complete process
• Include any/all pre-requisite steps
• Where there are options (e.g., linking a federated identity) show the most common path in detail

Add quality assurance checks.

• Ensure they are enforced during PRs
  • This can be done with a QA job within a workflow
• Consider adding pre-commit hooks to allow developers an easier way to confirm proper QA before creating a PR
• Some possible tools to use
  • markdownlint
  • Javascript linter
  • yamllint
  • actionlint
  • A spell checker of some sort
  • Others (this list is not exhaustive)
• Account for *.mdx files with one of the QA tools added here or a new/different one

Overview

We need a standard markdown "learn more" doc for the Cargo build file rule.

Additional context

It should follow the same format and style as the rest of the analytics docs. The doc should be called "cargo_build_file.md" to match the existing published link from the rule.

Acceptance Criteria

• The "Learn More" page is hosted at https://docs.phylum.io/analytics/cargo_build_file
• The "Issue Tags" page is updated with an entry and link to the new page
• A redirect entry is added to account for renaming the page from cargo_build_file_rule

Description

After lockfile generation support is added to the phylum-ci Docker image, the documentation for each of the integrations that makes use of that image needs to be updated.

Additional Details

• Ensure the difference between the phylum-ci image and the -slim version tags are made clear
• Updates are needed for each of these integrations
  • GitLab CI
  • Azure Pipelines
  • Bitbucket Pipelines
• The GitHub Actions integration doc update is covered by phylum-dev/phylum-analyze-pr-action#30
• Check with @louislang about possibly updating each of these integrations
  • Dazz
  • Sophos
  • Tines

Acceptance Criteria

• Documentation is updated

Docusaurus makes it easy for outside contributors to suggest changes by adding an "Edit this page" link to the footer of each hosted page. That link is simply to the hosted content on GitHub, with a message about forking the repo if the user is not a member of the organization. Therefore, the same CLA that is in place for the other public repos in the phylum-dev organization should be enabled for this repo. A webhook for the CLA app may be needed...check existing repos for the format.

Create a custom 404 page following the directions here and re-using existing Phylum 404 page content where possible (from the UI/app).

Overview

We need a standard markdown "learn more" doc for the "NPM Security Holding" rule.

Additional context

It should follow the same format and style as the rest of the analytics docs. The doc should be called "npm_security_holding.md" to match the existing published link from the rule.

Acceptance Criteria

• The "Learn More" page is hosted at https://docs.phylum.io/analytics/npm_security_holding
• The "Issue Tags" page is updated with an entry and link to the new page

Since this is a public repository, the settings should be locked down. Review the current settings and modify them as appropriate to match the current phylum-dev public repo standards.

Document the new Audit mode button for GitHub App Installations

See phylum-dev/roadmap#407

Description

After https://github.com/phylum-dev/rules/issues/425 is completed, change https://github.com/phylum-dev/documentation/blob/main/docs/analytics/trivial_package.md to describe the clarified name and intent of the rule.

Additional Details

Provide any additional details or context here.

Acceptance Criteria

• https://github.com/phylum-dev/documentation/blob/main/docs/analytics/trivial_package.md is moved to https://github.com/phylum-dev/documentation/blob/main/docs/analytics/minimal_code.md
• The content of the above documentation page is updated for the clarified name and intent of the Minimal Code rule.

Description

The project/group policy management UI pages have undergone changes that are not yet reflected in the documentation, so https://docs.phylum.io/knowledge_base/policy_apply page needs an update

Acceptance Criteria

• policy doc pages reflect the UI functionality updates
• screen grabs in policy doc pages are up-to-date

Overview

We need a standard markdown "learn more" doc for the "Depends on malware" rule.

Additional context

It should follow the same format and style as the rest of the analytics docs. The doc should be called "depends_on_malware.md" to match the existing published link from the rule.

Acceptance Criteria

• The "Learn More" page is hosted at https://docs.phylum.io/analytics/depends_on_malware
• The "Issue Tags" page is updated with an entry and link to the new page

The single package endpoint has 3 news top level keys in the json response. They are name, version, and ecosystem to help keep track of what response belong to which packages.

Overview

We need a standard markdown "learn more" doc for the npm URL dependency rule.

Additional context

It should follow the same format and style as the rest of the analytics docs. The doc should be called "npm_url_dependency.md" to match the (soon to be) existing published link from the rule.

Acceptance Criteria

• The "Learn More" page is hosted at https://docs.phylum.io/analytics/npm_url_dependency
• The "Issue Tags" page is updated with an entry and link to the new page

Overview

We need a standard markdown "learn more" doc for the base-64 decoding rule.

Additional context

It should follow the same format and style as the rest of the analytics docs. The doc should be called "base64_decoding.md".

Acceptance Criteria

• The "Learn More" page is hosted at https://docs.phylum.io/analytics/base64_decoding
• The "Issue Tags" page is updated with an entry and link to the new page

Description

Move pages from the phylum-dev/phylum-ci repo to the phylum-dev/documentation repo.

Additional Details

• Pages to move are identified in #24
• Coordinate the addition of pages with a corresponding removal from the source repo
• Keep the same frontmatter and file/page names
• Create a directory structure that makes sense for the receiving repo
• The content should not change at this time
  • There will be future issue(s) to clean up and normalize the content

Acceptance Criteria

• Pages exist in phylum-dev/documentation repo
• Pages have been removed from phylum-dev/phylum-ci repo

The current documentation, hosted on https://docs.phylum.io, consists of content from multiple sources:

• Public phylum-dev repositories
  • phylum-dev/documentation repo
    • Knowledge Base --> Policy section
    • "Home" category
  • phylum-dev/cli repo
    • "Support" category
    • Some of the "Knowledge Base" category
    • "Extensions" category
    • "Command Line Tool" category
  • phylum-dev/phylum-ci repo
    • "Integration" category
• Private phylum-dev repositories
  • A repo where the "analytics" (rules) are hosted
    • "Analytics" category
• Directly hosted pages on the site, created/edited within the Readme UI
  • Two pages in the "Knowledge Base" category
    • Phylum Package Score
    • Processing

This works because each repo has workflow(s) that push docs to the central Readme.com server using the rdme CLI. That is possible because the pages are centrally hosted (e.g., in a document storage schema) and asynchronous updates are allowed.

The new documentation will be hosted on GitHub Pages using Docusaurus, which is a static site generator. That means all the content needed to generate the site/docs is required to be in place at the time of generation. This poses a challenge given the current distributed nature of the individual documentation pages. There are several options for proceeding:

Option 1: Move all documentation files to the phylum-dev/documentation repo

Consolidate all docs from each source repo into a single place, the phylum-dev/documentation repo.

Pros:

• There is one place to go to update docs
• The generation procedure is greatly simplified
• Sidebar management and specification is easier to reason about
• The documentation can remain in a public repo
  • The "edit this page" link will work, allowing easier/more contributions

Cons:

• Documentation is not co-located with the code it documents
• It is more likely that developers will forget to update the docs
• Lose the ability to autogenerate templated docs
  • All the "Command Line Tool" category pages
  • Maybe also the "Analytics" category pages?

Option 2: Use a Docusaurus plugin

There is one plugin available to allow for downloading content from remote sources.

Pros:

• This is a plugin advertised by Docusaurus

Cons:

• It is only possible to specify specific files and not a directory or file glob
  • Adding new pages in remote repos requires a manual update
  • It is easy for pages to go out of sync over time due to file name or location changes
• The plugin is not updated very often and may go unsupported
  • The latest release was on 12 APR 2022
  • The last (non-dep bump) was seven months ago

Option 3: Use git submodules

Each repo hosting docs outside of phylum-dev/documentation could be added to phylum-dev/documentation as a git submodule.

Pros

• After updating each submodule, relative links would continue to work and show nicely in IDEs
• Docs continue to live with code, making updates easier and more likely

Cons

• Somewhat cumbersome to use
• Might be a bad idea to include private repos
• Still requires a method for triggering site generation when the source repos change

Option 4: Create a custom workflow that pulls content in

Create a triggerable workflow in the phylum-dev/documentation repo that checks out each of the remote repos hosting docs to copy their files over prior to generating the site.

Pros:

• Docs continue to live with code, making updates easier and more likely

Cons:

• Sidebar management is harder
• Specifying links to content from external repos is more error prone and the IDE niceties are lost
• There is more overhead/complexity added to each remote repo to ensure they trigger the custom workflow when their docs change

Option 5: Create multiple statically hosted sites

Create one for the documentation repo and one for each of the dynamically generated pages. At this point, that might just be cli.

Pros:

• Dynamically generated docs can continue to be generated in their own repo(s)

Cons:

• Splitting the documentation site up can be confusing to users
• The various sites might not stay in sync (e.g., releases, look and feel, links)
• Linking between sites is more error prone

Option 6: Combine some of the options above

Move the content that doesn't need to live in remote repos into the documentation repo. Create separate statically hosted sites for the remaining repo(s). Create "stub" pages in the main documentation repo to point to the full content.

Option 7: Something else

Maybe there is another option to consider that is not enumerated here.
Maybe using a monorepo would help.
Maybe using a Static Site Generator (SSG) is not the way to go.

Description

Move pages from private phylum-dev repo(s) to the phylum-dev/documentation repo.

Additional Details

• Pages to move are identified in #24
• Coordinate the addition of pages with a corresponding removal from the source repo
• Keep the same frontmatter and file/page names
• Create a directory structure that makes sense for the receiving repo
• The content should not change at this time
  • There will be future issue(s) to clean up and normalize the content

Acceptance Criteria

• Pages exist in phylum-dev/documentation repo
• Pages have been removed from private phylum-dev repo(s)

Overview

An integration for Phylum exists in the Dazz application; we should write documentation on how to install and use that integration.

Description

Not a high-pri, but would be nice if at least the dark color palette of the documentation matched the Phylum app UI.

Acceptance Criteria

• Dark theme is updated to resemble the Phylum app UI
• Light theme still works, uses colors that work for Phylum

Make use of the GitHub App or action to automate analysis of the docusaurus lockfile updates.

Overview

We need a standard markdown "learn more" doc for the Python build hook rule.

Additional context

It should follow the same format and style as the rest of the analytics docs. The doc should be called "python_build_hook.md" to match the existing published link from the rule.

Acceptance Criteria

• The "Learn More" page is hosted at https://docs.phylum.io/analytics/python_build_hook
• The "Issue Tags" page is updated with an entry and link to the new page

Overview

We need a standard markdown "learn more" doc for the compiled Python files rule.

Additional context

It should follow the same format and style as the rest of the analytics docs. The doc should be called "compiled_python_files.md" to match the existing published link from the rule.

Acceptance Criteria

• The "Learn More" page is hosted at https://docs.phylum.io/analytics/compiled_python_files
• The "Issue Tags" page is updated with an entry and link to the new page

Since this is a public repository, it should adhere to as many of the community standards as possible:

• README
• Code of Conduct
• Contributing guide
• License
  • Not sure which license should be used for documentation
  • Ask and also look for examples elsewhere
  • Decided to go with no explicit license
• Security Policy
• Issue templates
• PR template
• Enable repo admins to accept content reports