Instruction: ERTP (_Electronic Rights Transfer Protocol_) is Agoric’s token standard for digital assets in JavaScript. Using ERTP, you can easily create a wide variety of digital assets, all of which are transferred exactly the same way and with exactly the same security properties.
ERTP uses object capabilities to enforce access control. If your program has a reference to an object, it can call methods on that object. If it doesn’t have a reference, it can’t.
In order to understand the fundamentals of ERTP, it is important to understand the workings of the code that it builds on. Before digging into ERTP, it may help your bug finding efforts to become familiar with [Hardened JS/SES](https://agoric.com/documentation/guides/js-programming/ses/).
These resources should be helpful for building navigating ERTP:
* [ERTP Guide](https://agoric.com/documentation/getting-started/ertp-introduction.html)
* [ERTP API](https://agoric.com/documentation/ertp/api/)
* [Agoric’s JavaScript Programming Guide](https://agoric.com/documentation/guides/js-programming/), which includes Agoric-specific additions and deletions to general JavaScript programming that reviewers will need to be aware of.
* [Vats](https://agoric.com/documentation/guides/js-programming/vats.html) and [Far() and Remotable objects](https://agoric.com/documentation/guides/js-programming/far.html) are of note.
* [Eventual Send](https://agoric.com/documentation/guides/js-programming/eventual-send.html) requires calling `E(object.method)` for asynchronous communication between ERTP + Zoe. As a result of this, message ordering is important when communicating across vats, especially for ERTP.
* The [assert](https://github.com/Agoric/agoric-sdk/tree/master/packages/assert), [marshal](https://github.com/Agoric/agoric-sdk/tree/master/packages/marshal), and [notifier](https://github.com/Agoric/agoric-sdk/tree/master/packages/notifier) dependencies of the `agoric-sdk` may be important for understanding ERTP, but they are not presently within the scope of this program.
### Security Properties
ERTP purses have a deposit method which takes a payment as its argument. It first checks that the payment is genuine and the same asset brand as the purse
If everything passes the checks, the asset moves from the payment to the purse. If there’s a problem, it throws an error.
After a successful deposit, ERTP guarantees:
* The payment is deleted from its issuer’s records and no longer has any assets associated with it.
* Its issuer no longer recognizes that payment.
* The purse contains all digital assets that were in the payment.
When the deposit call throws an error (i.e. something went wrong), ERTP guarantees the purse and the alleged payment were unaffected by that call.
In addition, you can create a _deposit facet_ for any purse. This is an object associated with a specific purse that can be sent to another party instead of a reference to the purse. The security advantage is that the other party can only make deposits to the associated purse via the deposit facet. They cannot make a withdrawal from or ask about the balance of a purse via its deposit facet.
Breaking or violating any of these security properties would result in a significant security issue for the Agoric ecosystem, and issues in this code are high-value as Agoric moves towards launching a fully functional mainnet and economy.
Instruction: Recently, the Agoric team conducted an internal bug hunt to surface weaknesses, code flaws, and vulnerabilities in Zoe. To help hackers identify avenues of attack or areas of potential weakness, we recommend checking out the [Attacker's Guide to Zoe](https://github.com/Agoric/agoric-sdk/blob/master/packages/zoe/docs/AttackGuide.md), and the [audit-zestival](https://github.com/Agoric/agoric-sdk/issues?q=is%3Aissue+is%3Aopen+label%3Aaudit-zestival) tag in the`agoric-sdk`repo.
Zoe is Agoric’s smart contract framework, which is built on our [Electronic Rights Transfer Protocol (ERTP)](https://agoric.com/documentation/getting-started/ertp-introduction.html). Becoming familiar with the token standard will make it easier to navigate and test the code.
Zoe can be used to:
* *Run your code on-chain*
* *Mint new digital assets*
* *Credibly trade assets*
Zoe guarantees offer safety. When a user makes an [offer](https://agoric.com/documentation/glossary/#offer) and its payments are [escrowed](https://agoric.com/documentation/glossary/#escrow) with Zoe, Zoe guarantees that the user either gets what they said they wanted, or gets back (gets a refund) what they originally offered and escrowed. One reason this is possible is if a [proposal](https://agoric.com/documentation/glossary/#proposal) doesn’t match what the contract expects to do, it can immediately cause the [seat](https://agoric.com/documentation/glossary/#seat) to exit, getting back the amount it offered.
* [Intro to Zoe](https://agoric.com/documentation/getting-started/intro-zoe.html)
* [Zoe Contracts](https://agoric.com/documentation/zoe/guide/contracts/)
* [Zoe API](https://agoric.com/documentation/zoe/api/)
As part of our work towards production readiness of the Agoric stack, we are most interested in ensuring that the security promises and guarantees offered by Zoe can not be violated. Additionally, we are interested in ensuring that some of the fundamental architectural components of the Agoric stack are adequately battle tested. We encourage reporters to look into two of the most important pre-built contracts in the platform, the Automatic Market Maker and Vaults/Treasury.
Instruction: Hardened JavaScript is a tamper-proof JavaScript environment that allows safe execution of arbitrary programs in Compartments. It is the foundation of Agoric smart contracts, and a proposal to make this experimental this draft implementation an official language feature is currently a Stage 1 proposal to the ECMA TC39 committee.
Hardened JavaScript:
* Is a JavaScript runtime library for safely running third-party code.
* Addresses JavaScript’s lack of internal security, as JavaScript applications use and rely on third-party code (modules, packages, libraries, user-provided code for extensions and plug-ins, etc.).
* Enforces best practices by removing hazardous features such as global mutable state and lack of encapsulation in sloppy mode.
* Is a safe deterministic subset of “strict mode” JavaScript.
* Does not include any IO objects that provide [ambient authority (opens new window)](https://en.wikipedia.org/wiki/Ambient_authority) .
* Removes non-determinism by modifying a few built-in objects.
* Adds functionality to freeze and make immutable both built-in JavaScript objects and program created objects and make them immutable.
Helpful resources include:
* [HardenedJS/SES guide](https://agoric.com/documentation/guides/js-programming/ses/ses-guide.html#what-is-ses)
* [Hardened JS/SES reference](https://agoric.com/documentation/guides/js-programming/ses/ses-reference.html#lockdown-and-harden)
* [Purple Team Vulnerability Assessment](https://agoric.com/blog/technology/metamask-agoric-hardened-js-security-review/)
During a collaborative bug hunting exercise with Agoric’s code maintainers, the MetaMask team identified the targets listed below as potential hot spots for issues in the code.
* The evaluate function, including any of the transforms it performs, like re-inserting comments into trusted scope.
* Exploring ways of acquiring the scope handler from within a Compartment. While this was possible using Firefox debug tools, the use of developer tools was out-of-scope for this assessment, and no other approach was found.
* Experimenting with the ScopeProxy (which is reifiable), to try to get its feral eval function from it.
* Explore the implications of the Compartment constructor and evaluator tripping get and have traps on the object it’s given, and whether or not a confined script could craft a Proxy to allow re-entrancy and access to feral values.
In addition to this list, the areas outlined below have the potential to yield issues.
### Non-nested containment
When creating a fully virtualized Linux virtual machine within another fully virtualized virtual machine, a sandbox escape from the second machine should only land you into its creator and not any higher. However in hardened JavaScript, Compartments created by Compartments are “siblings”, both children managed equally by the hardened JavaScript system. Since Compartments running untrusted code can create and configure their own child Compartments, The Compartment must be secure against bad constructor parameters and configuration. If there was a way to create a Compartment configured to disable sandboxing, an attacker could use this to access the start compartment. It may be possible and desirable to implement the shim such that the Compartment implementation is re-defined in the context of the parent compartment, preventing an escape from leading directly to the start compartment.
### Compartment initialization could be interleaved by Component creator
The compartment initialization logic in the shim is particularly sensitive as it leverages the powerful eval. If an attacker was able to interleave malicious code at the right point during initialization, it may be able to access eval and break out to the start compartment. While this was not an active vulnerability at time of review, introducing this vulnerability only required a small code change. This attack was possible after a small change was introduced to the scopeProxyHandler implementation.
```
const c = new Compartment()
c.globalThis.__proto__ = new Proxy({}, { has (_, key) { debugger } })
```
### Obscure spec pitfalls
Many of the security features of hardened JavaScript depend on core JavaScript functionality, and the ECMAScript specification is so large that even the most capable experts cannot know the spec in its entirety. A fundamental change to JavaScript itself could introduce attack surface or vulnerabilities into hardened JavaScript as uncommon or poorly understood facets of the specification could break assumptions that the security guarantees of hardened JS rely on.
An example of this is present in the hardened JS shim as it relies on the `with` statement. The `with` statement is augmented by a `Symbol.unscopables` property, which is relatively obscure as it only augments the somewhat deprecated `with` statement. This could allow a breakage from the containment if it was not handled. In this case, JS does handle it. But in the `with ` statement section of the specification, there are no clear references to the `Symbol.unscopables` property and its effect on the `with` statement behavior. Other undocumented behaviors similar to this are likely exist in the specification, and significant changes to the spec that impact behaviors like this could introduce risk or vulnerability into hardened JavaScript.
