diff --git a/conf.py b/conf.py index c2de3b47..3d7f131e 100644 --- a/conf.py +++ b/conf.py @@ -21,20 +21,11 @@ # sys.path.insert(0, os.path.abspath('.')) -# -- General configuration ------------------------------------------------ - -# If your documentation needs a minimal Sphinx version, state it here. -# -# needs_sphinx = '1.0' - # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - 'sphinx.ext.autodoc', - 'sphinx.ext.napoleon', - 'sphinx.ext.mathjax', - 'recommonmark', + 'myst_parser', ] # Add any paths that contain templates here, relative to this directory. @@ -75,95 +66,25 @@ # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = False - -# -- Options for HTML output ---------------------------------------------- - # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # html_theme = 'sphinx_rtd_theme' - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -# -# html_theme_options = {} - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". html_static_path = [] - -# Custom sidebar templates, must be a dictionary that maps document names -# to template names. -# -# This is required for the alabaster theme -# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars -# html_sidebars = { -# '**': [ -# 'relations.html', # needs 'show_related': True theme option to display -# 'searchbox.html', -# ] -# } - - -# -- Options for HTMLHelp output ------------------------------------------ +html_theme_options = { + # Toc options + 'collapse_navigation': True, + 'sticky_navigation': True, + 'navigation_depth': 4, + 'includehidden': True, + 'titles_only': True, +} # Output file base name for HTML help builder. htmlhelp_basename = 'GRRdoc' -# -- Options for LaTeX output --------------------------------------------- - -latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - # - # 'papersize': 'letterpaper', - - # The font size ('10pt', '11pt' or '12pt'). - # - # 'pointsize': '10pt', - - # Additional stuff for the LaTeX preamble. - # - # 'preamble': '', - - # Latex figure (float) alignment - # - # 'figure_align': 'htmaster_dobp', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -latex_documents = [ - (master_doc, 'GRR.tex', u'GRR Documentation', - u'GRR team', 'manual'), -] - - -# -- Options for manual page output --------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - (master_doc, 'grr', u'GRR Documentation', - [author], 1) -] - -# -- Options for Texinfo output ------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - (master_doc, 'GRR', u'GRR Documentation', - author, 'GRR', 'One line description of project.', - 'Miscellaneous'), -] - -# Configure sphinx to convert markdown links (recommonmark is broken at the -# moment). +# Configure sphinx to replace predefined version variables. from docutils import nodes, transforms class ProcessLink(transforms.Transform): @@ -172,16 +93,11 @@ class ProcessLink(transforms.Transform): text_replacements = { "__GRR_VERSION__": "3.4.5.1", - "__GRR_DEB_VERSION__": "3.4.5-1" + "__GRR_DEB_VERSION__": "3.4.5-1", + "__FLEETSPEAK_PIP_VERSION__": "0.1.11" } def find_replace(self, node): - if isinstance(node, nodes.reference) and "refuri" in node: - r = node["refuri"] - if r.endswith(".md"): - r = r[:-3] + ".html" - node["refuri"] = r - if isinstance(node, nodes.Text): for k, v in self.text_replacements.items(): if k in node.astext(): @@ -204,12 +120,5 @@ def apply(self): self.current_level = 0 self.traverse(self.document) -from recommonmark.transform import AutoStructify - def setup(app): - app.add_config_value('recommonmark_config', { - 'enable_auto_toc_tree': True, - 'auto_toc_tree_section': 'Table of contents', - }, True) - app.add_transform(AutoStructify) app.add_transform(ProcessLink) diff --git a/deploying-grr-clients/index.md b/deploying-grr-clients/index.md index 279d605c..5e486133 100644 --- a/deploying-grr-clients/index.md +++ b/deploying-grr-clients/index.md @@ -1,10 +1,16 @@ # Deploying GRR clients -* [Overview](overview.md) -* [How to check if a deployed client talks back to GRR server](how-to-check-if-client-talks-back.md) -* [On Windows](on-windows.md) -* [On Mac OS X](on-mac-os-x.md) -* [On Linux](on-linux.md) -* [Life of a GRR client (what happens after deployment)](life-of-grr-client.md) -* [Client Protection](protection.md) -* [Troubleshooting ("I don't see my clients")](troubleshooting.md) +```{toctree} +--- +maxdepth: 1 +--- +Overview +How to check if a deployed client talks back to GRR server +On Windows +On macOS +On Linux +Life of a GRR client (what happens after deployment) +Client Protection +Troubleshooting ("I don't see my clients") +``` + diff --git a/developing-grr/implementation-details/index.md b/developing-grr/implementation-details/index.md index 8ed9390b..03bfb55c 100644 --- a/developing-grr/implementation-details/index.md +++ b/developing-grr/implementation-details/index.md @@ -1,6 +1,11 @@ # Implementation details -* [GRR messages](grr-messages.md) -* [Client Path Specification](client-path-spec.md) -* [Foreman](foreman.md) -* [Authorization and Auditing](authorizating-and-auditing.md) +```{toctree} +--- +maxdepth: 1 +--- +GRR messages +Client Path Specification +Foreman +Authorization and Auditing +``` diff --git a/developing-grr/index.md b/developing-grr/index.md index 124117b1..9cd73b08 100644 --- a/developing-grr/index.md +++ b/developing-grr/index.md @@ -1,7 +1,12 @@ # Developing GRR -* [Setting up development environment](setting-up-dev-env.md) -* [Running the tests](running-tests.md) -* [Contributing code](contributing.md) -* [Contributing documentation](contributing-docs.md) -* [Implementation details](implementation-details/index.md) +```{toctree} +--- +maxdepth: 1 +--- +Setting up development environment +Running the tests +Contributing code +Contributing documentation +Implementation details +``` diff --git a/fleetspeak/index.md b/fleetspeak/index.md index dfd86d8d..44fdc60b 100644 --- a/fleetspeak/index.md +++ b/fleetspeak/index.md @@ -1,5 +1,10 @@ # GRR and Fleetspeak setup -* [Installing from a release DEB (recommended)](from-release-deb.md) -* [Installing from source](from-source.md) -* [Scaling a fleetspeak setup](scaling.md) +```{toctree} +--- +maxdepth: 1 +--- +Installing from a release DEB (recommended) +Installing from source +Scaling a fleetspeak setup +``` diff --git a/index.md b/index.md index 5b94ec77..250c4826 100644 --- a/index.md +++ b/index.md @@ -18,14 +18,20 @@ GRR is open source (Apache License 2.0) and is developed on GitHub: [github.com/ ## Table of contents -* [What is GRR?](what-is-grr.md) -* [Quickstart](quickstart.md) -* [Installing GRR server](installing-grr-server/index.md) -* [Deploying GRR clients](deploying-grr-clients/index.md) -* [Investigating with GRR](investigating-with-grr/index.md) -* [Maintaining and tuning GRR deployment](maintaining-and-tuning/index.md) -* [GRR and Fleetspeak setup](fleetspeak/index.md) -* [Developing GRR](developing-grr/index.md) -* [Release Notes](release-notes.md) -* [F.A.Q](faq.md) -* [Publications](publications.md) +```{toctree} +--- +maxdepth: 2 +--- +What is GRR? +Quickstart +Installing GRR server +Deploying GRR clients +Investigating with GRR +Maintaining and tuning GRR deployment +GRR and Fleetspeak setup +Developing GRR +Release Notes +F.A.Q +Publications +``` + diff --git a/installing-grr-server/from-head-deb.md b/installing-grr-server/from-head-deb.md index 84f28ce9..5fff5ca8 100644 --- a/installing-grr-server/from-head-deb.md +++ b/installing-grr-server/from-head-deb.md @@ -1,9 +1,3 @@ -***Note on the AFF4 datastore deprecation*** - -*Starting from the version ***3.3.0.0*** GRR uses a new datastore format by default - ***REL_DB***. REL_DB is backwards-incompatible with the now-deprecated AFF4 datastore format (even though they both use MySQL as a backend).* - -*Use of AFF4-based deployments is now discouraged. REL_DB is expected to be much more stable and performant. Please see [these docs](../maintaining-and-tuning/grr-datastore.md) if you're upgrading an older GRR version and would like to try out the new datastore.* - # Installing from a HEAD DEB 1. If the Google Cloud SDK is not already installed, download a tarball for diff --git a/installing-grr-server/from-release-deb.md b/installing-grr-server/from-release-deb.md index 88dbfdf4..77fc614f 100644 --- a/installing-grr-server/from-release-deb.md +++ b/installing-grr-server/from-release-deb.md @@ -1,14 +1,8 @@ -***Note on the AFF4 datastore deprecation*** - -*Starting from the version ***3.3.0.0*** GRR uses a new datastore format by default - ***REL_DB***. REL_DB is backwards-incompatible with the now-deprecated AFF4 datastore format (even though they both use MySQL as a backend).* - -*Use of AFF4-based deployments is now discouraged. REL_DB is expected to be much more stable and performant. Please see [these docs](../maintaining-and-tuning/grr-datastore.md) if you're upgrading an older GRR version and would like to try out the new datastore.* - # Installing from a release server deb (recommended) This is the recommended way of installing the GRR server components. GRR server -debs are built for Ubuntu 18.04 Bionic. They may install on Debian or other Ubuntu -versions, but compatibility is not guaranteed. +debs are built for Ubuntu 18.04 Bionic (x86-64). They may install on Debian or other +Ubuntu versions, but compatibility is not guaranteed. 1. MySQL is GRR's default database backend, and should be up and running before installing GRR. The database framework can be run alongside GRR on the @@ -21,7 +15,22 @@ community edition of MySQL from Ubuntu repositories: If you have never installed MySQL on the machine before, you will be prompted for a password for the 'root' database user. After installation - completes, you will typically want to create a new database + completes, you need to change the `max_allowed_packet` setting, otherwise + GRR will have issues writing large chunks of data to the database. Put + the following into `/etc/mysql/my.cnf`: + + ``` + [mysqld] + max_allowed_packet=40M + ``` + + Then restart the MySQL server: + + ``` + service mysql restart + ``` + + You will typically want to create a new database user for GRR and give that user access an empty database that the GRR server installation will use: @@ -30,8 +39,6 @@ community edition of MySQL from Ubuntu repositories: ``` ```bash - mysql> SET GLOBAL max_allowed_packet=41943040; - mysql> CREATE USER 'grr'@'localhost' IDENTIFIED BY 'password'; mysql> CREATE DATABASE grr; diff --git a/installing-grr-server/from-released-pip.md b/installing-grr-server/from-released-pip.md index ac3fee44..4e3eff4e 100644 --- a/installing-grr-server/from-released-pip.md +++ b/installing-grr-server/from-released-pip.md @@ -1,9 +1,3 @@ -***Note on the AFF4 datastore deprecation*** - -*Starting from the version ***3.3.0.0*** GRR uses a new datastore format by default - ***REL_DB***. REL_DB is backwards-incompatible with the now-deprecated AFF4 datastore format (even though they both use MySQL as a backend).* - -*Use of AFF4-based deployments is now discouraged. REL_DB is expected to be much more stable and performant. Please see [these docs](../maintaining-and-tuning/grr-datastore.md) if you're upgrading an older GRR version and would like to try out the new datastore.* - # Installing from released PIP packages If the templates included in release server debs are not diff --git a/installing-grr-server/from-source.md b/installing-grr-server/from-source.md index 76e765ac..db4c16a7 100644 --- a/installing-grr-server/from-source.md +++ b/installing-grr-server/from-source.md @@ -1,114 +1,130 @@ -***Note on the AFF4 datastore deprecation*** - -*Starting from the version ***3.3.0.0*** GRR uses a new datastore format by default - ***REL_DB***. REL_DB is backwards-incompatible with the now-deprecated AFF4 datastore format (even though they both use MySQL as a backend).* +# Installing from source -*Use of AFF4-based deployments is now discouraged. REL_DB is expected to be much more stable and performant. Please see [these docs](../maintaining-and-tuning/grr-datastore.md) if you're upgrading an older GRR version and would like to try out the new datastore.* +Here's how to install GRR from source (from github HEAD). This method is useful when you intend to do some development or when you need to build GRR for an architecture not supported by the binary distribution (i.e. arm64 or PowerPC). -# Installing from source +For the instructions below, we assume that Ubuntu 18 is used. -Here's how to install GRR for development (from github HEAD): +## Prerequisites First, install the prerequisites: -* Ubuntu: - ```bash -sudo apt install -y fakeroot debhelper libffi-dev libssl-dev python-dev \ - python-pip wget openjdk-8-jdk zip git devscripts dh-systemd dh-virtualenv \ - libc6-i386 lib32z1 asciidoc +sudo apt-get update +sudo apt install -y fakeroot debhelper libffi-dev libssl-dev python3-dev \ + python3-pip python3-venv wget openjdk-8-jdk zip git devscripts dh-systemd \ + dh-virtualenv libc6-i386 lib32z1 asciidoc libmysqlclient-dev + +# Go (version 1.13 or newer) is needed to build Fleetspeak. If you already +# have Go installed on your system, you can skip this part. +# We use amd64 version here, you might need to download another Go +# distribution matching your architecture (see https://go.dev/dl/). +wget https://go.dev/dl/go1.17.3.linux-amd64.tar.gz +sudo bash -c "rm -rf /usr/local/go && tar -C /usr/local -xzf go1.17.3.l +inux-amd64.tar.gz" +export PATH=$PATH:/usr/local/go/bin ``` -* Centos: -```bash -sudo yum install -y epel-release python-devel wget which java-1.8.0-openjdk \ - libffi-devel openssl-devel zip git gcc gcc-c++ redhat-rpm-config rpm-build \ - rpm-sign +## Building Fleetpseak -sudo yum install -y python-pip -``` +Fleetspeak is a communication middleware (effectively, a client and a server) +used by GRR to communicate with endpoints. GRR is tightly integrated with +Fleetspeak and expects Fleetspeak binaries to be present in +`fleetspeak-server-bin` and `fleetspeak-client-bin` PIP packages. -Next, upgrade pip and install virtualenv: +Create and activate a Python virtualenv at $HOME/INSTALL: ```bash -sudo pip install --upgrade pip virtualenv +python3 -m venv $HOME/INSTALL +source $HOME/INSTALL/bin/activate +pip install --upgrade pip setuptools wheel ``` -Next, download the github repo and cd into its directory: +Next, build `fleetspeak-server-bin` and `fleetspeak-client-bin` Python packages. +These packages are effectively Python PIP package wrappers around Fleetspeak +binaries. ```bash -git clone https://github.com/google/grr.git +# Check out Fleetspeak. +git clone https://github.com/google/fleetspeak.git +# This is needed for Protobuf builds. +pip install grpcio-tools -cd grr -``` +cd fleetspeak/ +pip install -e fleetspeak_python/ +./fleetspeak/build.sh +./fleetspeak/build-pkgs.sh -Finally, create a virtualenv at $HOME/INSTALL and install GRR in the virtualenv: +python fleetspeak/server-wheel/setup.py bdist_wheel --package-root fleetspeak/server-pkg/debian/fleetspeak-server/ --version __FLEETSPEAK_PIP_VERSION__ +pip install dist/fleetspeak_server_bin-__FLEETSPEAK_PIP_VERSION__-py2.py3-none-linux_x86_64.whl -```bash -virtualenv $HOME/INSTALL +python fleetspeak/client-wheel/setup.py bdist_wheel --package-root fleetspeak/client-pkg/debian/fleetspeak-client/ --version __FLEETSPEAK_PIP_VERSION__ +pip install dist/fleetspeak_client_bin-__FLEETSPEAK_PIP_VERSION__-py2.py3-none-linux_x86_64.whl -travis/install.sh +cd .. ``` -You should now be able to run GRR commands from inside the virtualenv, e.g: +Now, when you do `pip freeze`, you should see `fleetspeak-server-bin` and `fleetspeak-client-bin` installed inside the virtualenv: ```bash -source $HOME/INSTALL/bin/activate - -grr_config_updater initialize # Initialize GRR's configuration - +$ pip freeze +... +fleetspeak-client-bin @ file:///home/foo/fleetspeak/dist/fleetspeak_client_bin-__FLEETSPEAK_PIP_VERSION__-py2.py3-none-linux_x86_6 +4.whl +fleetspeak-server-bin @ file:///home/foo/fleetspeak/dist/fleetspeak_server_bin-__FLEETSPEAK_PIP_VERSION__-py2.py3-none-linux_x86_64.whl +... ``` -# Installing Python 3 GRR version from source - -***Note on the Python 3 support in GRR*** - -*By now GRR codebase should be fully Python 3 compatible: unit and end-to-end tests are passing in a properly setup Python 3 GRR environment. However, the first Python 3 GRR release is expected in Dec. 2019. Until that's done, Python 3 support should be treated as experimental: unforeseen packaging issues not covered by our tests are possible.* +## Building GRR -Here's how to install GRR for Python 3 development (from github HEAD, on Ubuntu Xenial): - -First, install the prerequisites: - -```bash -sudo apt install -y fakeroot debhelper libffi-dev libssl-dev python3-dev \ - python3-pip python3-venv wget openjdk-8-jdk zip git devscripts dh-systemd \ - dh-virtualenv libc6-i386 lib32z1 asciidoc libmysqlclient-dev -``` - -Next, download the github repo and cd into its directory: +Next, you need to build GRR. Download the GitHub repo and cd into its directory: ```bash git clone https://github.com/google/grr.git - cd grr ``` -Next, create a virtualenv at $HOME/INSTALL: +### If your goal is development + +Run the following script to install GRR into the virtualenv: ```bash -python3 -m venv $HOME/INSTALL +./travis/install.sh ``` -Next, pre-install Python 3-compatible chipsec version into the virtualenv. Note that this will install chipsec Python code only, no driver will be built, meaning that Chipsec won't be function on GRR clients (this should be fixed soon). +Please check [Installing from a release server deb](./from-release-deb.md) for +instructions on how to configure MySQL server. + +You should now be able to run GRR commands from inside the virtualenv, +particularly, you can trigger GRR server configuration. ```bash source $HOME/INSTALL/bin/activate - -pip install https://github.com/chipsec/chipsec/archive/python3-beta.zip --install-option="--skip-driver" +grr_config_updater initialize # Initialize GRR's configuration ``` -Finally, install GRR in the virtualenv: +Then, to run individual GRR components (for a Fleetspeak-enabled configuration): ```bash -travis/install.sh +# To run fleetspeak server. +grr_server --component fleetspeak_server --verbose +# To run AdminUI. +grr_server --component admin_ui --verbose +# To run the worker. +grr_server --component worker --verbose +# To run the frontend. +grr_server --component frontend --verbose ``` -You should now be able to run GRR commands from inside the virtualenv, e.g: +### If your goal is to build a custom GRR client template -```bash -source $HOME/INSTALL/bin/activate - -grr_config_updater initialize # Initialize GRR's configuration +In this case you don't need a full blown GRR server setup. Run the following: +```bash +./travis/install_client_builder.sh ``` +This will install necessary PIP packages into your virtualenv to run the +`grr_client_build` command. See +[Building custom client templates](../maintaining-and-tuning/building-custom-client-templates.md) +for how to use it. diff --git a/installing-grr-server/index.md b/installing-grr-server/index.md index 1807a019..6718e1c4 100644 --- a/installing-grr-server/index.md +++ b/installing-grr-server/index.md @@ -1,10 +1,16 @@ # Installing GRR Server -* [Overview](overview.md) -* [Securing access to GRR server (important)](securing-access.md) -* [Installing from a release DEB (recommended)](from-release-deb.md) -* [Installing from a HEAD DEB](from-head-deb.md) -* [Installing from released PIP packages](from-released-pip.md) -* [Installing from source](from-source.md) -* [Installing via GRR Docker image](via-docker.md) -* [Troubleshooting ("GRR server doesn't seem to run")](troubleshooting.md) +```{toctree} +--- +maxdepth: 1 +--- +Overview +Securing access to GRR server (important) +Installing from a release DEB (recommended) +Installing from a HEAD DEB +Installing from released PIP packages +Installing from source +Installing via GRR Docker image +Troubleshooting ("GRR server doesn't seem to run") +``` + diff --git a/installing-grr-server/overview.md b/installing-grr-server/overview.md index 0040af3f..f93c9832 100644 --- a/installing-grr-server/overview.md +++ b/installing-grr-server/overview.md @@ -27,12 +27,6 @@ The GRR client **is not a server component** but it comes bundled with GRR serve #### GRR Datastore The data store acts both as a central storage component for data, and as a communication mechanism for all GRR server components. -***Note on the AFF4 datastore deprecation*** - -*Starting from the version ***3.3.0.0*** GRR uses a new datastore format by default - ***REL_DB***. REL_DB is backwards-incompatible with the now-deprecated AFF4 datastore format (even though they both use MySQL as a backend).* - -*Use of AFF4-based deployments is now discouraged. REL_DB is expected to be much more stable and performant. Please see [these docs](../maintaining-and-tuning/grr-datastore.md) if you're upgrading an older GRR version and would like to try out the new datastore.* - #### Fleetspeak server This component terminates the streaming HTTPS connections from the fleetspeak clients and implements the communication protocol. It receives messages from clients and delivers queued messages to the clients. diff --git a/investigating-with-grr/artifacts/index.md b/investigating-with-grr/artifacts/index.md index ef66a834..7a1e8cd0 100644 --- a/investigating-with-grr/artifacts/index.md +++ b/investigating-with-grr/artifacts/index.md @@ -1,5 +1,10 @@ # Artifacts -* [Overview](overview.md) -* [Collecting](collecting.md) -* [Defining](defining.md) +```{toctree} +--- +maxdepth: 1 +--- +Overview +Collecting +Defining +``` diff --git a/investigating-with-grr/flows/index.md b/investigating-with-grr/flows/index.md index 7797ae19..3b8c23ba 100644 --- a/investigating-with-grr/flows/index.md +++ b/investigating-with-grr/flows/index.md @@ -1,8 +1,13 @@ # Flows -* [What are Flows and how to use them](what-are-flows.md) -* [Starting Flows](starting.md) -* [Specifying File Paths](specifying-file-paths.md) -* [Literal and Regex Matching](literal-and-regex-matching.md) -* [Specifying Windows Registry paths](specifying-windows-registry-paths.md) -* [Working with Flow results](working-with-results.md) +```{toctree} +--- +maxdepth: 1 +--- +What are Flows and how to use them +Starting Flows +Specifying File Paths +Literal and Regex Matching +Specifying Windows Registry paths +Working with Flow results +``` diff --git a/investigating-with-grr/hunts/index.md b/investigating-with-grr/hunts/index.md index 4aa48600..584c690c 100644 --- a/investigating-with-grr/hunts/index.md +++ b/investigating-with-grr/hunts/index.md @@ -1,10 +1,15 @@ # Hunts -* [What are "hunts" and how to use them](what-are-hunts.md) -* [Starting Hunts](starting.md) -* [Hunt Rules](rules.md) -* [Hunt Limits, DOs and DONTs](limits.md) -* [Hunt Controls](controlling-hunts.md) -* [Working with Hunt results](working-with-results.md) -* [Rapid hunts](rapid-hunts.md) -* [Troubleshooting ("Why is my hunt doing nothing?")](troubleshooting.md) +```{toctree} +--- +maxdepth: 1 +--- +What are "hunts" and how to use them +Starting Hunts +Hunt Rules +Hunt Limits, DOs and DONTs +Hunt Controls +Working with Hunt results +Rapid hunts +Troubleshooting ("Why is my hunt doing nothing?") +``` diff --git a/investigating-with-grr/index.md b/investigating-with-grr/index.md index 38535d87..1434e702 100644 --- a/investigating-with-grr/index.md +++ b/investigating-with-grr/index.md @@ -1,18 +1,22 @@ # Investigating with GRR -* [Overview](overview.md) -* [Client-Server communication](client-server-communication.md) -* [Security considerations](security-considerations.md) -* [Searching for a client](searching-for-client.md) -* [Flows](flows/index.md) -* [Hunts](hunts/index.md) -* [Virtual File System](vfs/index.md) -* [Artifacts](artifacts/index.md) -* [Cron Jobs in GRR](cron-jobs.md) -* [Osquery](osquery.md) -* [Automation with GRR API](automation-with-api.md) -* [Interactive scripting](interactive-scripting.md) -* [Output Plugins](output-plugins.md) -* [Emergency Code and Binary Pushes](pushing-code.md) -* [Glossary](glossary.md) - +```{toctree} +--- +maxdepth: 1 +--- +Overview +Client-Server communication +Security considerations +Searching for a client +Flows +Hunts +Virtual File System +Artifacts +Cron Jobs in GRR +Osquery +Automation with GRR API +Interactive scripting +Output Plugins +Emergency Code and Binary Pushes +Glossary +``` diff --git a/investigating-with-grr/vfs/index.md b/investigating-with-grr/vfs/index.md index 3d5d74a8..b4c4754a 100644 --- a/investigating-with-grr/vfs/index.md +++ b/investigating-with-grr/vfs/index.md @@ -1,5 +1,10 @@ # Virtual File System -* [Intro](virtual-file-system.md) -* [Navigating the VFS](navigation.md) -* [Timelines](timelines.md) +```{toctree} +--- +maxdepth: 1 +--- +Intro +Navigating the VFS +Timelines +``` diff --git a/maintaining-and-tuning/building-custom-client-templates.md b/maintaining-and-tuning/building-custom-client-templates.md index b0b56dd9..27e35a41 100644 --- a/maintaining-and-tuning/building-custom-client-templates.md +++ b/maintaining-and-tuning/building-custom-client-templates.md @@ -1,5 +1,10 @@ # Building custom client templates +## Building the templates + +Note: templates have to be built on a target platform (i.e. if you need a +Windows 10 GRR client template, you have to build on Windows 10). + After [installing the GRR server components](../installing-grr-server/overview.md), you can build client templates with @@ -8,13 +13,27 @@ you can build client templates with grr_client_build build --output mytemplates ``` -and repack them with +If you can't install prebuilt Debian or PIP packages, you'd need to install +GRR from source. You might choose to install the full server or just +the packages needed to build the templates. Please see +[Installing from source](../installing-grr-server/from-source.md) for details. + + +## Repacking the templates + +The templates are generic GRR client builds that have to be repacked to be used +with a particular GRR server deployment. Repacking is a process that injects +server-specific configuration (like the frontend address, labels, etc). + +While templates have to be built on the client target platform, repacking +has to be done on your GRR server, as GRR server contains the configuration +(i.e., crypto credentials for the clients to use). ```bash grr_client_build repack --template mytemplates/*.zip --output_dir mytemplates ``` -The first step needs to be done on the client target platform while the repacking step happens on your GRR server machine that knows about the proper configuration (i.e., crypto credentials for the clients to use). +## Samples We have fully automated client builds for Linux, OSX and Windows. The scripts we use are mostly in the [Travis](https://github.com/google/grr/tree/master/travis) diff --git a/maintaining-and-tuning/configuration/index.md b/maintaining-and-tuning/configuration/index.md index 313c92cc..f62ca3f0 100644 --- a/maintaining-and-tuning/configuration/index.md +++ b/maintaining-and-tuning/configuration/index.md @@ -1,6 +1,12 @@ # Changing GRR server configuration -* [Configuration file organization](file-organization.md) -* [Configuration contexts](contexts.md) -* [Parameter Expansion](parameter-expansion.md) -* [Filtering](filtering.md) +```{toctree} +--- +maxdepth: 1 +--- +Configuration file organization +Configuration contexts +Parameter Expansion +Filtering +``` + diff --git a/maintaining-and-tuning/index.md b/maintaining-and-tuning/index.md index 07638432..ed317752 100644 --- a/maintaining-and-tuning/index.md +++ b/maintaining-and-tuning/index.md @@ -1,14 +1,19 @@ # Maintaining and tuning GRR deployment -* [Changing GRR server configuration](configuration/index.md) -* [Key management](key-management/index.md) -* [User management](user-management/index.md) -* [Email configuration](email-configuration.md) -* [Monitoring](monitoring.md) -* [Approval-based access control](approval-based-workflow.md) -* [Repacking GRR clients](repacking-clients.md) -* [Low-level maintenance with grr_console](low-level-maintenance-with-console.md) -* [GRR datastore](grr-datastore.md) -* [Scaling GRR](scaling.md) -* [Building custom client templates](building-custom-client-templates.md) -* [Troubleshooting](troubleshooting.md) +```{toctree} +--- +maxdepth: 1 +--- +Changing GRR server configuration +Key management +User management +Email configuration +Monitoring +Approval-based access control +Repacking GRR clients +Low-level maintenance with grr_console +GRR datastore +Scaling GRR +Building custom client templates +Troubleshooting +``` diff --git a/maintaining-and-tuning/key-management/index.md b/maintaining-and-tuning/key-management/index.md index 8ece1e0e..2c974d86 100644 --- a/maintaining-and-tuning/key-management/index.md +++ b/maintaining-and-tuning/key-management/index.md @@ -1,4 +1,9 @@ # Key management -* [Which keys are used in GRR and how](which-keys-and-how.md) -* [Rotating the keys](rotating.md) +```{toctree} +--- +maxdepth: 1 +--- +Which keys are used in GRR and how +Rotating the keys +``` diff --git a/maintaining-and-tuning/monitoring.md b/maintaining-and-tuning/monitoring.md index d23937f3..3be0ed0d 100644 --- a/maintaining-and-tuning/monitoring.md +++ b/maintaining-and-tuning/monitoring.md @@ -19,7 +19,7 @@ Fleetspeak servers; otherwise feel free to skip the relevant steps, which are marked as **FS**. 1. Install GRR, for example from -[pip](../installing-grr-server/from-released-pip.html). +[pip](../installing-grr-server/from-released-pip.md). 1. Run the GRR components locally. Execute each of the three commands in a separate terminal: diff --git a/maintaining-and-tuning/user-management/authentication.md b/maintaining-and-tuning/user-management/authentication.md index d3a1c612..f2e0fddd 100644 --- a/maintaining-and-tuning/user-management/authentication.md +++ b/maintaining-and-tuning/user-management/authentication.md @@ -4,7 +4,7 @@ GRR has a concept of users of the system. The GUI supports basic authentication and this verfication of user identity is used in all auditing functions (so for example GRR can properly record which user accessed which client, and who executed flows on clients). **There is no logout button. To change users you will need to invalidate your session.** -A GRR user will be created as an admin by default. This is only important if the [approval-based workflow](../approval-based-auditing.md) is turned on, since only "admin" users can approve hunts. We are aware of a bug that all users are created with admin permissions, however, the approval system is the authority for access across GRR, when enabled. +A GRR user will be created as an admin by default. This is only important if the [approval-based workflow](../approval-based-workflow.md) is turned on, since only "admin" users can approve hunts. We are aware of a bug that all users are created with admin permissions, however, the approval system is the authority for access across GRR, when enabled. To add the user joe as an admin: diff --git a/maintaining-and-tuning/user-management/index.md b/maintaining-and-tuning/user-management/index.md index 2538ce13..c6cb0df2 100644 --- a/maintaining-and-tuning/user-management/index.md +++ b/maintaining-and-tuning/user-management/index.md @@ -1,6 +1,11 @@ # User management -* [User authentication](authentication.md) -* [Running GRR UI behind Apache](running-behind-apache.md) -* [Running GRR UI behind Nginx](running-behind-nginx.md) -* [Limiting access to GRR UI/API with API routers](limiting-access-with-routers.md) +```{toctree} +--- +maxdepth: 1 +--- +User authentication +Running GRR UI behind Apache +Running GRR UI behind Nginx +Limiting access to GRR UI/API with API routers +``` diff --git a/maintaining-and-tuning/user-management/limiting-access-with-routers.md b/maintaining-and-tuning/user-management/limiting-access-with-routers.md index cd70024f..ff7b896e 100644 --- a/maintaining-and-tuning/user-management/limiting-access-with-routers.md +++ b/maintaining-and-tuning/user-management/limiting-access-with-routers.md @@ -11,7 +11,7 @@ GRR has a few predefined API routers: - *DisabledApiCallRouter* - a router that will return an error for all possible requests. - *ApiCallRouterWithoutChecks* *(default)* - a router that performs no access checks and just gives blanket access to the system. -- *ApiCallRouterWithApprovalChecks* - a router that enables GRR approvals-based workflow for better auditing. See [Approval-based auditing](../approval-based-auditing.md) for more details. +- *ApiCallRouterWithApprovalChecks* - a router that enables GRR approvals-based workflow for better auditing. See [Approval-based workflow](../approval-based-workflow.md) for more details. - *ApiCallRobotRouter* - a router that provides limited access to the system that is suitable for automation. Normally used together with *ApiCallRouterWithApprovalChecks* so that scripts and robots can perform actions without getting approvals. ## Various configuration scenarios diff --git a/requirements.txt b/requirements.txt index 5ba6d837..017b8dbe 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,30 +1,29 @@ alabaster==0.7.12 -Babel==2.9.0 -certifi==2020.12.5 -chardet==4.0.0 -commonmark==0.9.1 -docutils==0.16 -idna==2.10 -imagesize==1.2.0 -Jinja2==2.11.3 -livereload==2.6.3 -MarkupSafe==1.1.1 -packaging==20.9 -Pygments==2.7.4 -pyparsing==2.4.7 -pytz==2021.1 -recommonmark==0.7.1 -requests==2.25.1 -six==1.15.0 -snowballstemmer==2.1.0 -Sphinx==3.4.3 -sphinx-autobuild==2020.9.1 -sphinx-rtd-theme==0.5.1 +attrs==21.2.0 +Babel==2.9.1 +certifi==2021.10.8 +charset-normalizer==2.0.7 +docutils==0.17.1 +idna==3.3 +imagesize==1.3.0 +Jinja2==3.0.3 +markdown-it-py==1.1.0 +MarkupSafe==2.0.1 +mdit-py-plugins==0.2.8 +myst-parser==0.15.2 +packaging==21.3 +Pygments==2.10.0 +pyparsing==3.0.6 +pytz==2021.3 +PyYAML==6.0 +requests==2.26.0 +snowballstemmer==2.2.0 +Sphinx==4.3.0 +sphinx-rtd-theme==1.0.0 sphinxcontrib-applehelp==1.0.2 sphinxcontrib-devhelp==1.0.2 -sphinxcontrib-htmlhelp==1.0.3 +sphinxcontrib-htmlhelp==2.0.0 sphinxcontrib-jsmath==1.0.1 sphinxcontrib-qthelp==1.0.3 -sphinxcontrib-serializinghtml==1.1.4 -tornado==6.1 -urllib3==1.26.3 +sphinxcontrib-serializinghtml==1.1.5 +urllib3==1.26.7