docs

sphinx/dev_process/project_docs.rst

@@ -30,16 +30,24 @@ Edit the conf.py file similar to
 Edit Documentation and View
 =============================
 
-Add documentation in the documentation directory.  Organize in subdirectories where
-logical.
+Add documentation in the documentation directory.
+
+Write all documents in ReStructured
+Text or Markdown (The requirements-docs.txt should contain both sphinx and myst-parser
+to handle each format.  Organize in logical subdirectories.
+
+Each document must contain only one top-level title, which will be displayed in the
+Table of Contents.  Any number of sub-level headings may be included in each document.
 
 Edit the index.rst file to include page names under the Table of Contents (toctree).
 These should include paths relative to the documentation directory, and filenames
-without extension, similar to
-`index.rst <../index.rst>`_.
+without extension, similar to `index.rst <../index.rst>`_.  The :maxdepth parameter
+indicates how many sublevels will be displayed in the Table of Contents.  Only if there
+are very few pages should :maxdepth be more than 1.
 
 In the documentation directory, run the following to build pages locally and check
-formatting::
+formatting.  The command will build documentation and print errors and warnings
+in the terminal output.  Run this prior to pushing to Github::
 
   make html
 
@@ -67,8 +75,12 @@ For Github Action, add YAML configuration files
 Create a yaml file to initiate a github action with a file in ./.github/workflows, like
 `build_sphinx_docs.yml <../../.github/workflows/build_sphinx_docs.yml>`_.
 
-Optional?: Add `<.readthedocs.yaml <../../.readthedocs.yaml>`_ and
-`environment.yml <../../environment.yml>`_ for the build.
+TODO: test this after setup branch to publish from
+------------------------------------------------------
+
+Add `<.readthedocs.yaml <../../.readthedocs.yaml>`_ and
+`environment.yml <../../environment.yml>`_ for the build.  This will ensure that the
+dependencies are installed and that index.html page will be the landing site.
 
 Set Pages Site to branch created by Github action
 --------------------------------------------------------

sphinx/index.rst

@@ -11,7 +11,6 @@ Welcome to Specify Developer documentation!
    aws/aws_specify_cloud_setup
    aws/client_migration_notes
    aws/ec2_rds_specify7_setup
-   aws/aws_security
    aws/specify_cloud_graviton_setup
 
 .. toctree::
@@ -34,7 +33,9 @@ Welcome to Specify Developer documentation!
    :maxdepth: 1
    :caption: Security:
 
+   security/aws_security
    security/fix_exposed_secret
+   security/monitoring
 
 .. toctree::
    :maxdepth: 1

sphinx/aws/aws_security.rst → sphinx/security/aws_security.rst

@@ -4,6 +4,9 @@ AWS Security
 TODO:
 ========
 
+Research
+-------------------
+
 Security best practices, including:
 
 * role overview
@@ -14,6 +17,14 @@ Security best practices, including:
   and access resources, so how best to deal with account numbers, usernames,
   role names, secret names, domain names, bucket names, etc
 
+Root user
+------------------
+
+* https://docs.aws.amazon.com/wellarchitected/latest/security-pillar/sec_securely_operate_aws_account.html
+* MFA should be enabled on it
+* only used for functions that require it
+* Disable programmatic access
+* Disallow creating of access keys for root account
 
 References
 ==================

sphinx/security/monitoring.rst

@@ -0,0 +1,17 @@
+Security Monitoring
+######################
+
+
+GitGuardian
+=====================
+
+Account managed by Alec, Aimee, Grant, Max
+
+Add organizations (lifemapper, biotaphy, specify, specifysystems) to Github integration
+
+Check incidents, after determining that any risk is invalid, or has been revoked and
+deleted, mark the incident as **Ignored** or **Resolved**.
+
+Ignore repositories that we do not own (i.e. Max's)
+
+Warnings are pushed to the Specify **updown-monitoring** Slack channel