roost.tools / coop
Mirror of https://github.com/roostorg/coop github.com/roostorg/coop
0
fork

Configure Feed

Select the types of activity you want to include in your feed.

Update HMA documentation (#71)

* Remove HMA service from DEVELOPMENT.md

Removed HMA service entry from the development documentation. It has to be started up separately

docker compose up --build -d hma

* Update DEVELOPMENT.md with HMA setup details

Added HMA development instructions and image URL accessibility notes.

* Enhance USER_GUIDE with HMA setup and management details

Added detailed instructions for setting up and managing hash banks in HMA.

* add HMA images and update user guide

---------

Co-authored-by: Juliet Shen <juliet@roost.tools>

authored by

juliet
Juliet Shen and committed by
GitHub 771e66af 30e3d576

+35 -2
+15 -1
docs/DEVELOPMENT.md
··· 46 46 Kafka | 29092 | Event streaming 47 47 Schema Registry | 8081 | Kafka schemas 48 48 Zookeeper | 22181 | Kafka coordination 49 - HMA | 5000 | Hash Matching Algorithm service 50 49 Jaeger | 16686 | Tracing UI (opens automatically) 51 50 OTEL Collector | 4317 | Telemetry collection 52 51 ··· 166 165 - `server/graphql/generated.ts` 167 166 168 167 Schema changes trigger recompilation of both client and server. If you experience regeneration loops, stop watch mode and run manually. 168 + 169 + ## HMA Development 170 + HMA is not started automatically with `npm run up`. Start it separately if you're doing hash matching: `docker compose up --build -d hma` 171 + 172 + HMA is pre-configured in `server/.env` with `HMA_SERVICE_URL=http://localhost:5000`. No additional environment setup is needed for local development. 173 + 174 + ### Image URL Accessibility 175 + When submitting items to Coop, image URLs must be reachable by the HMA Docker container and not just your browser or the Node.js server. 176 + HMA fetches the image itself to compute the hash. This means localhost URLs will silently fail: HMA will return empty hashes, the image similarity signal will not evaluate, and no rule will fire. 177 + 178 + For local development, if you're serving images from your host machine, add the following to /etc/hosts: 179 + 180 + 127.0.0.1 host.docker.internal 181 + 182 + Then use `host.docker.internal:<port>` in image URLs when submitting items. This URL resolves correctly from both the browser and inside Docker. 169 183 170 184 ## Troubleshooting 171 185
+20 -1
docs/USER_GUIDE.md
··· 208 208 209 209 210 210 #### Hash Banks 211 - Coop integrates with hasher-matcher-actioner (HMA), providing a configurable way to match known CSAM, non-consensual intimate imagery, terrorist and violent extremist content, and any internal hash banks you maintain. Setup requires API credentials from supported hash databases like NCMEC and Tech Against Terrorism. Read more about HMA documentation here. 211 + Coop integrates with [hasher-matcher-actioner (HMA)](https://github.com/facebook/ThreatExchange/tree/main/hasher-matcher-actioner/), providing a configurable way to match known CSAM, non-consensual intimate imagery, terrorist and violent extremist content, and any internal hash banks you maintain. Setup requires API credentials from supported hash databases like NCMEC and StopNCII. Read more about HMA documentation [here]([https://github.com/facebook/ThreatExchange/tree/main/hasher-matcher-actioner](https://github.com/facebook/ThreatExchange/tree/main/hasher-matcher-actioner/docs)). 212 212 213 213 HMA signals are available as a signal in Coop’s signal library. 214 + 215 + ##### Setting Up HMA 216 + How you set things up depends on your use case: 217 + 218 + * If items are submitted by user reports (`POST /api/v1/report`): no enforcement rule is needed. Reported items are automatically enqueued to MRT, and routing rules will direct them to the right queue. Simply create a routing rule with the image hash condition and your target queue. 219 + 220 + * If items are submitted via the items API `(POST /api/v1/items/async/)` and you want Coop to proactively flag matches without a user report: you need an automated enforcement rule with the image hash condition and a "Send to Manual Review" action. Optionally pair it with a routing rule to direct matches to a specific queue (otherwise they go to the default queue). 221 + 222 + ##### Managing hash banks 223 + 224 + Banks created directly in HMA (e.g. via the HMA UI or seed scripts) will not appear in Coop's Matching Banks UI unless they are also registered in the hash_banks table. The recommended approach is to create banks through the Coop UI (Settings → Matching Banks), which registers the bank in both HMA and Coop's database automatically. 225 + 226 + ![Coop matching banks page showing a test hash bank created in the Coop UI](./images/coop-hma.png) 227 + 228 + 229 + Banks created through Coop are named in HMA using the convention COOP_<ORGID>_<NORMALIZED_NAME> — for example, a bank named "Test Bank" for org e7c89ce7729 becomes `COOP_E7C89CE7729_TEST_BANK` in HMA. This is what you will see in the HMA UI. You can use the HMA UI to manually add content to the bank for local testing. 230 + 231 + ![HMA UI showing the bank created in Coop, along with a modal that appears if you manually upload media to the matching bank](./images/hma-ui-coop-banks.png) 232 + 214 233 215 234 #### Location Banks 216 235 ![Creating a location bank for the middle of Times Square using a geohash](./images/coop-location-bank.png)
docs/images/coop-hma.png

This is a binary file and will not be displayed.

docs/images/hma-routing-rule.png

This is a binary file and will not be displayed.

docs/images/hma-ui-coop-banks.png

This is a binary file and will not be displayed.