Better example organization

[zardus]

The examples are being overwhelmed with similar "start here, explore to here, print flag" writeups. These are good to have for testing, because they tend to explore different types of code, help us keep writeups working as angr evolves, and so on, but they're redundant for people trying to learn angr.

I think we need to have an "Examples Showcase" that shows unique examples, and a "Additional Examples" section that contains redundancies for CI (and curious readers). Putting this issue as a placeholder for now. Next step is building the list.

[Kingloko]

I have categorized the examples into the following categories:

1. constrain_symbol (set up symbol, add constraints, set target address and run)
2. file_system (some sort of file system operation was needed)
3. hook (function hooking was needed)
4. obfuscation
5. pwn
6. simple (load binary, set target address, run)
7. misc

It was a helpful learning exercise, but if this is still something you all are looking for I'd be happy to push my changes.

[ltfish]

An example might belong to more than one category. Is it a tagging-based organization?

[Kingloko]

Not really, I just moved the examples around into folders. Examples were placed into the most specific folder that I could see them being placed into. So for instance: all the examples in the "Constrain Symbol" directory could also be placed in the simple directory but not vice versa.

You can check it out here:https://github.com/Kingloko/angr-doc/tree/master/examples

I'd love to discuss a tagging system thou, how would you envision that working?

[rhelmot]

The best way to do this probably isn't by changing the file organization but rather to have categories in the actual examples page in the docs that serve as the "tags". right now the organization is really coarse, and could be split into something a lot more granular.

(I do agree that the filesystem organization kind of sucks right now but probably the way to fix that is by binary origin, not example purpose)

[zardus]

What's more, I went through a while back and actually cut down on the number of examples we actually describe in the main examples page (https://github.com/angr/angr-doc/blob/master/docs/examples.md), moving a lot of redundant ones to a "more examples" page (https://github.com/angr/angr-doc/blob/master/docs/more-examples.md). We might want to split that latter page into README.md files in their respective example folders, and have a tagged list of them at the bottom of examples.md.

There's probably a mathematical proof that the type of optimal example organization we're going for is undecidable, though.

[Kingloko]

How about this:
What if we made an api-examples.md file where we tag examples of how each section of the api gets used in real CTF problems.
Then, when people add examples from CTFs the tag which angr "capabilities" they took advantage of when they solved the challenge.

I think this will be a really useful compliment to the api documentation and book.

[github-actions]

This issue has been marked as stale because it has no recent activity. Please comment or add the pinned tag to prevent this issue from being closed.

[github-actions]

This issue has been closed due to inactivity.