add landing page and rules website #2310

williballenthin · 2024-08-20T20:45:30Z

This PR adds the landing page that will be found at https://mandiant.github.io/capa/ and a rule browsing web application that will be found at https://mandiant.github.io/capa/rules/.

You can view a snapshot of the site here: https://williballenthin.github.io/capa/

The rules website was written by @DeeyaSingh and developed here: https://github.com/DeeyaSingh/DeeyaSingh.github.io
I imported the code in 53d270a and have since then made some tweaks, primarily around styling and integration with the larger site.

The landing page definitely needs more work - the wording isn't great and there's a few more sections needed (especially an "examples" section). But, I figured it's better to have something to work with than to wait for perfection. Therefore, please don't hesitate to open PRs extending the landing page.

Checklist

No CHANGELOG update needed

No new tests needed

No documentation update needed

closes #2261
closes #1550
closes #1554
closes #1555
closes #1556
closes #1557

produced via: ``` asciinema capa.cast ./capa Practical\ Malware\ Analysis\ Lab\ 01-01.dll_ <ctrl-d> agg --no-loop --theme solarized-light capa.cast capa.gif ```

…ns-1

…i-actions-1

Use the Pygments syntax-highlighting library to parse and render the YAML rule content. This way we don't have to manually traverse the rule nodes and emit lists; instead, we rely on the fact that YAML is pretty easy for humans to read and let them consume it directly, with some text formatting to help hint at the types/structure.

capa (the library) has routines for deserializing the YAML content into structured objects, which means we can use tools like mypy to find bugs. So, prefer to use those routines instead of parsing YAML ourselves.

Run and fix the issues identified by the following linters: - isort - black - ruff - mypy

Add links to the following external resources: - GitHub rule source in capa-rules repo - VirusTotal search for matching samples

Update the rules landing page to accept a HTTP query parameter named "q" that specifies an initial search term to to pass to pagefind. This enables external pages link to rule searches.

Import header from root capa landing page.

github-actions

Please add bug fixes, new features, breaking changes and anything else you think is worthwhile mentioning to the master (unreleased) section of CHANGELOG.md. If no CHANGELOG update is needed add the following to the PR description: [x] No CHANGELOG update needed

CHANGELOG updated or no update needed, thanks! 😄

.github/workflows/web-deploy.yml

mr-tz

This is awesome! Thanks for getting us started here.
Do we want to keep the Examples links in the header and footer even though there is none yet? Otherwise, looks good to me!

fariss

Great work! The site is shaping up nicely.
I've left some comments for future separate improvements

web/rules/scripts/modified-dates.py

fariss · 2024-08-21T13:52:33Z

web/public/index.html

    <style>
-      /*
-        Josh's Custom CSS Reset
-        https://www.joshwcomeau.com/css/custom-css-reset/
-      */
-      *, *::before, *::after {
-        box-sizing: border-box;
+      :root {
+        /* from the icon */
+        --capa-blue: #2593d7;
+        --capa-blue-darker: #1d74aa;
+
+        --bs-primary: var(--capa-blue);
+        --bs-primary-rgb: var(--capa-blue);
      }
-      * {
-        margin: 0;
+
+      a:not(.btn) {
+        color: var(--capa-blue);
+        text-decoration: none;
      }
-      body {
-        line-height: 1.5;
-        -webkit-font-smoothing: antialiased;
+
+      a:not(.btn):hover {
+        text-decoration: underline;
+      }
+
+      .btn-primary {
+        --bs-btn-bg: var(--capa-blue);
+        --bs-btn-border-color: var(--capa-blue);
+      }
+
+      .btn:hover {
+        background-color: var(--capa-blue-darker);
+        border-color: var(--capa-blue-darker);
      }
-      img, picture, video, canvas, svg {
-        display: block;
-        max-width: 100%;
+
+      .text-justify {
+        text-align: justify;
+      }
+
+      body {
+        overflow-x: clip;
      }
-      input, button, textarea, select {
-        font: inherit;
+
+      /* a link that looks like inline text, until you hover and see a colorful underline */
+      .understated-link {
+        color: var(--bs-body-color) !important;
+        text-decoration: none;
+        text-decoration-color: var(--capa-blue);
      }
-      p, h1, h2, h3, h4, h5, h6 {
-        overflow-wrap: break-word;
+
+      .understated-link:hover {
+        text-decoration: underline;
+        text-decoration-color: var(--capa-blue) !important;
      }
-      #root, #__next {
-        isolation: isolate;
+
+      .b-divider {
+        width: 100%;
+        height: 3rem;
+        background-color: rgba(0, 0, 0, .1);
+        border: solid rgba(0, 0, 0, .15);
+        border-width: 1px 0;
+        box-shadow: inset 0 .5em 1.5em rgba(0, 0, 0, .1), inset 0 .125em .5em rgba(0, 0, 0, .15);
      }
    </style>


The inline styles could be moved to a separate CSS file

web/rules/readme.md

fariss · 2024-08-21T14:05:37Z

web/rules/scripts/build_rules.py

+                    <li><a href="{gh_link}">edit on GitHub</a></li>
+                    <li><a href="{vt_link}">search on VirusTotal</a></li>


Ideally, external links should be opened in a new tab (target="_blank") and use rel="noopener noreferrer"

Interesting, my expectations are that a typical click opens in the same tab, and a middle click opens in a new tab, and that this customization is best left up to the user.

fariss · 2024-08-21T14:14:07Z

web/rules/scripts/modified-dates.py

+start_dir = sys.argv[1]
+output_file = sys.argv[2]


Maybe use argparser with descriptions for these dirs

@DeeyaSingh

That's a great idea! I'll work on changing that

williballenthin · 2024-08-21T15:38:43Z

will address code style violations and then mark the PR ready for review again

DeeyaSingh

Looks great! I love the landing page you've added and the other enhancements to the design.

mr-tz · 2024-08-22T08:06:22Z

Amazing, thank you all very much!

williballenthin and others added 18 commits August 12, 2024 14:25

web: index: add gif of capa running

d8f073b

index: add screencast of running capa

12232c1

produced via: ``` asciinema capa.cast ./capa Practical\ Malware\ Analysis\ Lab\ 01-01.dll_ <ctrl-d> agg --no-loop --theme solarized-light capa.cast capa.gif ```

web: index: start to sketch out style

b98f133

Merge branch 'master' of github.com:mandiant/capa into wb/webui-actio…

46b19b2

…ns-1

Merge branch 'master' of public.github.com:mandiant/capa into wb/webu…

c83545d

…i-actions-1

web: landing page

115ee93

web: merge rules website

53d270a

web: rules: update bootstrap and integrate rules

f080a38

web: rules: use capa to load rule content

0feb3ea

capa (the library) has routines for deserializing the YAML content into structured objects, which means we can use tools like mypy to find bugs. So, prefer to use those routines instead of parsing YAML ourselves.

web: rules: linters

63efc25

Run and fix the issues identified by the following linters: - isort - black - ruff - mypy

web: rules: add some links to rule page

e3ccdca

Add links to the following external resources: - GitHub rule source in capa-rules repo - VirusTotal search for matching samples

web: rules: accept ?q= parameter for initial search

a2d7f8e

Update the rules landing page to accept a HTTP query parameter named "q" that specifies an initial search term to to pass to pagefind. This enables external pages link to rule searches.

web: rules: add link to namespace search

34ecced

web: rules: use consistent header

d3813f9

Import header from root capa landing page.

web: rules: add umami script

d574c80

web: add initial whats new section, TODOs

8a1a803

web: rules: remove old images

4b94e6d

williballenthin added enhancement New feature or request rule website related to rule content web visualization webui related to capa results web visualization labels Aug 20, 2024

williballenthin requested review from mr-tz, fariss, mike-hunhoff and DeeyaSingh August 20, 2024 20:45

Merge branch 'master' into web-landing-rules

741741e

github-actions bot previously requested changes Aug 20, 2024

View reviewed changes

changelog

4b900d5

williballenthin commented Aug 20, 2024

View reviewed changes

.github/workflows/web-deploy.yml Outdated Show resolved Hide resolved

williballenthin added 2 commits August 20, 2024 22:51

Delete web/rules/public/js/bootstrap-4.5.2.min.js

fc6ed2b

Delete web/public/img/capa.cast

2c98e99

williballenthin mentioned this pull request Aug 20, 2024

web: update landing page #2277

Closed

3 tasks

mr-tz approved these changes Aug 21, 2024

View reviewed changes

This comment was marked as resolved.

Sign in to view

fariss approved these changes Aug 21, 2024

View reviewed changes

williballenthin added 3 commits August 21, 2024 16:34

Rename readme.md to README.md

1837427

web: rules: add scripts to pre-commit configs

0d35f0a

Merge branch 'master' into web-landing-rules

e2e116e

williballenthin marked this pull request as draft August 21, 2024 15:38

DeeyaSingh approved these changes Aug 21, 2024

View reviewed changes

williballenthin added 5 commits August 21, 2024 20:31

web: rules: add scripts to pre-commit configs

b990da2

Merge branch 'master' into web-landing-rules

9d54348

lints

2526983

ci: add temporary branch push trigger to get incremental builds

228de41

web: rules: assert start_dir must exist

07af410

williballenthin marked this pull request as ready for review August 21, 2024 20:49

williballenthin force-pushed the web-landing-rules branch 2 times, most recently from 4f2273c to ddc469b Compare August 22, 2024 07:01

ci: web: rules: deep checkout so we can get rule history

5d585ac

williballenthin force-pushed the web-landing-rules branch from ddc469b to 5d585ac Compare August 22, 2024 07:02

williballenthin added 5 commits August 22, 2024 07:17

web: rules: check output of subprocess

636e6b8

web: rules: factor out common CSS

435ea96

web: rules: fix header links

3c61693

web: rules: only index rule content, not surrounding text

155ac4c

ci: web: remote temporary branch push trigger

e57702b

williballenthin merged commit a33f67b into mandiant:master Aug 22, 2024
5 of 9 checks passed

williballenthin deleted the web-landing-rules branch August 22, 2024 07:42

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

add landing page and rules website #2310

add landing page and rules website #2310

williballenthin commented Aug 20, 2024 •

edited

Loading

github-actions bot left a comment

mr-tz left a comment

This comment was marked as resolved.

fariss left a comment

fariss Aug 21, 2024

fariss Aug 21, 2024

williballenthin Aug 21, 2024

fariss Aug 21, 2024

williballenthin Aug 21, 2024

DeeyaSingh Aug 21, 2024

williballenthin commented Aug 21, 2024

DeeyaSingh left a comment

mr-tz commented Aug 22, 2024

		<li><a href="{gh_link}">edit on GitHub</a></li>
		<li><a href="{vt_link}">search on VirusTotal</a></li>

add landing page and rules website #2310

add landing page and rules website #2310

Conversation

williballenthin commented Aug 20, 2024 • edited Loading

Checklist

github-actions bot left a comment

Choose a reason for hiding this comment

mr-tz left a comment

Choose a reason for hiding this comment

This comment was marked as resolved.

fariss left a comment

Choose a reason for hiding this comment

fariss Aug 21, 2024

Choose a reason for hiding this comment

fariss Aug 21, 2024

Choose a reason for hiding this comment

williballenthin Aug 21, 2024

Choose a reason for hiding this comment

fariss Aug 21, 2024

Choose a reason for hiding this comment

williballenthin Aug 21, 2024

Choose a reason for hiding this comment

DeeyaSingh Aug 21, 2024

Choose a reason for hiding this comment

williballenthin commented Aug 21, 2024

DeeyaSingh left a comment

Choose a reason for hiding this comment

mr-tz commented Aug 22, 2024

williballenthin commented Aug 20, 2024 •

edited

Loading